Webhooks

Documentation Index

Fetch the complete documentation index at: https://help.withallo.com/llms.txt

Use this file to discover all available pages before exploring further.

​

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

​

How to set up webhooks

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"]
  }'

​

Webhook payload format

{
  "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"
  }
}

​

Security

• Your endpoint URL must use HTTPS.
• Every webhook includes a cryptographic signature in the webhook-signature header. 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.

​

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

​

Need help?