> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surge.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> How Surge webhook delivery works: event types, retry behavior, and where to configure your endpoint.

Surge sends an HTTP POST to a URL you configure whenever something happens in your project: a message arrives, a contact opts out, a campaign is approved. You register one endpoint URL per project and filter by `type` in your handler.

## Where to configure your endpoint

Webhook endpoints are configured at the project level in the dashboard, under the top-level **Webhooks** page. A project-level endpoint receives events from all accounts under that project.

## Event taxonomy

Surge can send the following events to your webhook endpoint depending on the subscriptions you configure:

| Category     | Events                                                                    |
| ------------ | ------------------------------------------------------------------------- |
| Message      | `message.sent`, `message.delivered`, `message.failed`, `message.received` |
| Contact      | `contact.opted_in`, `contact.opted_out`                                   |
| Conversation | `conversation.created`                                                    |
| Campaign     | `campaign.approved`                                                       |
| Phone number | `phone_number.attached_to_campaign`                                       |
| Link         | `link.followed`                                                           |
| Voice        | `call.ended`, `recording.completed`, `voicemail.received`                 |

## Envelope shape

Every webhook payload has the same outer envelope:

```json theme={null}
{
  "id": "evt_01jav96823f9x9054d6gyzpp16",
  "type": "message.received",
  "timestamp": "2024-10-21T23:29:43Z",
  "account_id": "acct_01jrz...",
  "data": { ... }
}
```

The `data` object varies by event type. See the individual event pages for their payload shapes.

## Retries and timeouts

* Surge expects a `2xx` response within the request timeout. If your endpoint doesn't respond in time or returns a non-2xx status, Surge retries with exponential back-off.
* Your handler should be idempotent. Surge may deliver the same event more than once.
* Return `200` quickly; enqueue work for slow processing.

## Signature verification

Every request includes Standard Webhooks signature headers. You should verify the signature before processing the payload. See [Signature Verification](./signature-validation) for the full details and per-language examples.

## Setting up a handler

For a walkthrough of configuring your endpoint, verifying signatures, and handling events in our SDKs, see [Receiving Messages & Webhooks](../../receiving/index).