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

# Webhooks overview

> Receive event-driven updates for Dugble messaging and audience resources

Webhooks let an application react to Dugble lifecycle changes without repeatedly polling resource endpoints.

<Warning>
  Customer-configurable outgoing webhooks are currently a preview. The current
  subscribable catalog includes Email, SMS, contact, suppression, and
  broadcast lifecycle events. See the event catalog for the exact event names.
</Warning>

## How webhook delivery works

<Steps>
  <Step title="Register an HTTPS endpoint">
    Add an endpoint in your Dugble team settings and select one or more
    supported events your application needs.
  </Step>

  <Step title="Return a successful response quickly">
    Verify and persist the event, return a `2xx` response, and perform slow
    work asynchronously.
  </Step>

  <Step title="Handle retries and duplicates">
    Webhook delivery is an at-least-once process. Use the event ID as an
    idempotency key before applying side effects.
  </Step>
</Steps>

## Build your endpoint now

You can prepare an endpoint around a small dispatcher:

```ts theme={null}
app.post("/webhooks/dugble", async (request, response) => {
    // Verify X-Dugble-Signature against the raw body before decoding JSON.
    const event = request.body;

    if (await eventStore.has(event.id)) {
        return response.sendStatus(200);
    }

    await eventStore.save(event.id, event);

    switch (event.type) {
        case "sms.delivered":
            await markSmsDelivered(event.data.id);
            break;
        case "contact.updated":
            await refreshContact(event.object_id);
            break;
    }

    response.sendStatus(200);
});
```

See the event catalog for the canonical event envelope, supported event types,
and signature header contract.

<Card title="Verify signatures" icon="key" href="/docs/webhooks/signatures">
  Authenticate requests with the raw body and your endpoint signing secret.
</Card>

## When polling is still useful

Webhooks remove the need for routine polling, but direct resource retrieval is
still useful for reconciliation or when your application needs the latest full
resource state:

* `GET /emails/{message_id}` for email
* `GET /sms/{message_id}` for SMS
* `POST /sms/{message_id}/sync-status` to request an SMS provider status refresh

<Card title="Event catalog" icon="bolt" href="/docs/webhooks/events">
  Review the supported lifecycle events and suggested application behavior.
</Card>

<Card title="Operational controls" icon="gauge" href="/docs/webhooks/operations">
  Monitor endpoint health, recover failures, and control delivery traffic.
</Card>