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

# Overview

> Receive real-time notifications when events occur in your Allo account

Webhooks let Allo push events to your server in real time. When something happens — a call finishes, an SMS arrives, a contact is created — Allo sends an HTTPS POST request to your endpoint with the event data.

## How it works

1. An event occurs in your Allo account (e.g., a call is completed).
2. Allo sends an HTTPS POST request to the URL you configured.
3. Your server receives the request, verifies the signature, and processes the event.

## 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 full data (recording, transcript, 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                                               |

See the [Event catalog](/en/v2/api-reference/webhooks/event-catalog) for full payload schemas.

## Payload format

Every webhook uses the same envelope format:

```json theme={null}
{
  "topic": "call.completed",
  "version": "2.0",
  "timestamp": "2025-03-15T14:30:45.123456Z",
  "data": {
    // Event-specific fields
  }
}
```

| Field       | Type   | Description                                         |
| ----------- | ------ | --------------------------------------------------- |
| `topic`     | string | Event type (e.g., `call.completed`, `sms.received`) |
| `version`   | string | Payload version, always `"2.0"`                     |
| `timestamp` | string | ISO 8601 timestamp when the event was sent          |
| `data`      | object | Event-specific payload                              |

## Quickstart

<Steps>
  <Step title="Create a webhook endpoint">
    Go to [Settings > Webhooks](https://web.withallo.com/settings/webhooks) in your Allo dashboard. Add your HTTPS endpoint URL and select the events you want to receive. The webhook applies to all Allo numbers in your workspace.
  </Step>

  <Step title="Handle incoming requests">
    Your endpoint receives POST requests with the event payload in the body. Return a `2xx` 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>

## Next steps

<CardGroup cols={2}>
  <Card title="Event catalog" icon="list" href="/en/v2/api-reference/webhooks/event-catalog">
    Full reference for all events and their payloads
  </Card>

  <Card title="Verifying signatures" icon="shield-halved" href="/en/v2/api-reference/webhooks/verifying-signatures">
    Authenticate incoming webhooks with HMAC-SHA256
  </Card>
</CardGroup>