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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.