Webhooks
Receive real-time HTTP notifications as soon as an event occurs in e-Signal. No more polling — react instantly.
20+ eventsHMAC-SHA256Automatic retriesReal-time logs
Setup
1
Set the receiving URL
In Dashboard → Settings → Webhooks, add the HTTPS URL of your endpoint.
2
Select events
Choose which event types to receive. You can filter by channel or by threshold.
3
Get your secret
A unique HMAC secret is generated. Store it in an environment variable.
4
Verify signatures
Every request includes an X-ESignal-Signature-256 header. Verify it to confirm the request origin.
Payload structure
Each webhook is an HTTP POST with the Content-Type: application/json header. Example for message.received:
JSON payload
{
"id": "evt_01JAB5XQKPZN3MWV...",
"type": "message.received",
"created_at": "2025-11-20T14:10:23Z",
"data": {
"id": "msg_01JAB4...",
"conversation_id": "conv_01J7P3...",
"contact": {
"id": "cnt_01J8X4...",
"name": "Kofi Asante",
"phone": "+233241234567"
},
"channel": "whatsapp",
"direction": "inbound",
"type": "text",
"content": "Hello, is this available?",
"ai": {
"sentiment": "positive",
"intent": "inquiry",
"score": 0.76
}
}
}HTTP headers
Respond with 200 quickly
e-Signal expects a 2xx response within 10 seconds. Process the webhook in a background job to avoid timeouts.
Signature verification
Every webhook request is signed with HMAC-SHA256. Always verify the signature before processing the event.
import hmac
import hashlib
def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
"""Verifies the HMAC-SHA256 signature of an e-Signal webhook."""
expected = hmac.new(
secret.encode(),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
# In your Flask/Django/FastAPI handler:
# sig = request.headers.get("X-ESignal-Signature-256")
# if not verify_signature(request.data, sig, WEBHOOK_SECRET):
# return 401Retry policy
⚡
1st
Immediate
🔄
2nd
+30s
⏱️
3rd
+5 min
⏰
4th
+30 min
🕐
5th
+2h
After 5 failed attempts, the webhook is marked as failed and you receive an email. Webhooks can be replayed manually from the dashboard.