Webhooks send automatic HTTP notifications to your server when events happen in your Allo account — a call finishes, an SMS arrives, a contact is created, and more.
What you can do with webhooks
- Log calls and messages in your CRM or database
- Trigger workflows when calls finish or SMS arrive
- Sync contacts with external systems
- Build real-time dashboards and alerts
Available events
| Event | Description |
|---|---|
call.received | Inbound call starts ringing |
call.triggered | Outbound call initiated |
call.answered | Call answered on the other side |
call.completed | Call finished with recording, transcript, and summary |
tag.added | Tag added to a call |
tag.removed | Tag removed from a call |
sms.received | Inbound SMS received |
sms.sent | Outbound SMS sent |
contact.created | Contact created |
contact.updated | Contact updated |
How to set up webhooks
Get an API key
Go to Settings > API and create an API key with the WEBHOOKS_READ_WRITE scope.
Create a webhook endpoint
curl -X POST https://api.withallo.com/v2/webhooks \
-H "Authorization: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/allo",
"topics": ["call.completed", "sms.received"]
}'
Handle incoming requests
Your server receives a POST request for each event. Return a 200 status code within 20 seconds to acknowledge receipt.
Verify signatures
Every webhook includes a cryptographic signature. Verify it to ensure the request came from Allo. See Verifying signatures.
Open integrations
Go to Settings > Integrations > Webhooks in the Allo mobile app.
Enable webhooks
Toggle the webhook switch on.
Configure your URL
Enter your HTTPS endpoint URL. The URL must be publicly accessible.
Select events
Choose which events you want to receive.
Test the connection
Tap Test to send a test event to your endpoint and verify it works.
Webhook payload format
Every webhook uses the same envelope:
{
"topic": "call.completed",
"version": "2.0",
"timestamp": "2025-03-15T14:45:00.000Z",
"data": {
"id": "cll_2NfDKEm9sF8xK3pQr1Zt",
"from_number": "+33612345678",
"to": "+33112345678",
"type": "INBOUND",
"result": "ANSWERED",
"summary": "Customer called about a billing question.",
"recording_url": "https://storage.withallo.com/recordings/abc123.mp3"
}
}
For the full payload specification of each event, see the Event catalog.
Security
- Your endpoint URL must use HTTPS.
- Every webhook includes a cryptographic signature in the
webhook-signatureheader. Verify it to ensure the request is authentic. - Store your signing secret securely — treat it like a password.
Reliability
- Allo retries failed deliveries up to 8 times over approximately 27.5 hours with exponential backoff.
- If your endpoint fails continuously for 5 days, it is automatically disabled.
- You can recover missed events by replaying them after fixing your endpoint.
See Delivery and retries for the full retry schedule.
Example implementations
const express = require("express");
const app = express();
app.post(
"/webhooks/allo",
express.raw({ type: "application/json" }),
(req, res) => {
const event = JSON.parse(req.body);
switch (event.topic) {
case "call.completed":
console.log("Call finished:", event.data.id);
break;
case "sms.received":
console.log("SMS from:", event.data.from_number);
break;
}
res.sendStatus(200);
}
);
app.listen(3000);
from flask import Flask, request
app = Flask(__name__)
@app.route("/webhooks/allo", methods=["POST"])
def handle_webhook():
event = request.get_json()
if event["topic"] == "call.completed":
print(f"Call finished: {event['data']['id']}")
elif event["topic"] == "sms.received":
print(f"SMS from: {event['data']['from_number']}")
return "", 200
Troubleshooting
Webhook not receiving events
Verify your endpoint is publicly accessible over HTTPS. Check that the webhook is enabled and subscribed to the correct event types. Use the test endpoint to verify.
Getting timeout errors
Your endpoint must respond within 20 seconds. Return 200 immediately and process the event in the background.
Receiving duplicate events
This is expected — Allo guarantees at-least-once delivery. Use the webhook-id header to deduplicate. See Best practices.
Signature verification failing
Make sure you use the raw request body (not parsed JSON) for verification. Check that your signing secret is correct and your server clock is accurate. See Verifying signatures.
Need help?
Complete webhook API documentation
Get help from the Allo team