# 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
        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](/docs/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
{
  "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](/docs/webhooks/event-catalog).

## Security

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

See [Delivery and retries](/docs/webhooks/delivery-and-retries) for the full retry schedule.

## Example implementations

<Tabs>
  <Tab title="Node.js">
    ```javascript
    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
    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](/docs/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](/docs/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](/docs/webhooks/verifying-signatures).
  </Accordion>
</AccordionGroup>

## Need help?

<CardGroup cols={2}>
  <Card title="Full API reference" icon="book" href="/docs/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>
