> ## 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.

# Webhooks

> Receive real-time notifications when calls, SMS, and contacts events happen in your Allo account

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

<Tabs>
  <Tab title="Via the API">
    <Steps>
      <Step title="Get an API key">
        Go to [Settings > API](https://web.withallo.com/settings/api) and create an API key with the `WEBHOOKS_READ_WRITE` scope.
      </Step>

      <Step title="Create a webhook endpoint">
        ```bash theme={null}
        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"]
          }'
        ```
      </Step>

      <Step title="Handle incoming requests">
        Your server receives a POST request for each event. Return a `200` status code within 20 seconds to acknowledge receipt.
      </Step>

      <Step title="Verify signatures">
        Every webhook includes a cryptographic signature. Verify it to ensure the request came from Allo. See [Verifying signatures](/en/v2/api-reference/webhooks/verifying-signatures).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Via the mobile app">
    <Steps>
      <Step title="Open integrations">
        Go to **Settings > Integrations > Webhooks** in the Allo mobile app.
      </Step>

      <Step title="Enable webhooks">
        Toggle the webhook switch on.
      </Step>

      <Step title="Configure your URL">
        Enter your HTTPS endpoint URL. The URL must be publicly accessible.
      </Step>

      <Step title="Select events">
        Choose which events you want to receive.
      </Step>

      <Step title="Test the connection">
        Tap **Test** to send a test event to your endpoint and verify it works.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Webhook payload format

Every webhook uses the same envelope:

```json theme={null}
{
  "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](/en/v2/api-reference/webhooks/event-catalog).

## Security

* Your endpoint URL must use **HTTPS**.
* Every webhook includes a cryptographic signature in the `webhook-signature` header. [Verify it](/en/v2/api-reference/webhooks/verifying-signatures) 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](/en/v2/api-reference/webhooks/delivery-and-retries#bulk-recovery) by replaying them after fixing your endpoint.

See [Delivery and retries](/en/v2/api-reference/webhooks/delivery-and-retries) for the full retry schedule.

## Example implementations

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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](/en/v2/api-reference/webhooks/testing) to verify.
  </Accordion>

  <Accordion title="Getting timeout errors">
    Your endpoint must respond within 20 seconds. Return `200` immediately and process the event in the background.
  </Accordion>

  <Accordion title="Receiving duplicate events">
    This is expected — Allo guarantees at-least-once delivery. Use the `webhook-id` header to deduplicate. See [Best practices](/en/v2/api-reference/webhooks/best-practices#implement-idempotency).
  </Accordion>

  <Accordion title="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](/en/v2/api-reference/webhooks/verifying-signatures).
  </Accordion>
</AccordionGroup>

## Need help?

<CardGroup cols={2}>
  <Card title="Full API reference" icon="book" href="/en/v2/api-reference/webhooks/overview">
    Complete webhook API documentation
  </Card>

  <Card title="Contact support" icon="headset" href="mailto:support@withallo.com">
    Get help from the Allo team
  </Card>
</CardGroup>