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

# Webhooks

> Have Autocampaign AI tell your own systems automatically when something happens, with signed and retried deliveries.

## Overview

**Not a developer?** A [webhook](/getting-started/glossary#webhook) is a way for
another program to be told automatically when something happens here — for
example, when a new contact is added. Your developer sets it up; send them this
page. Three terms you'll hear. The **endpoint URL** is the web address on their
side that receives each notice. The **payload** is the data inside each notice.
The **signing secret** is a shared password that proves each notice really came
from Autocampaign AI.

Webhooks push events from Autocampaign AI to your own URL as they happen — for
example, when a contact is created or a campaign completes. Manage them at
**Settings → Webhooks** (`/settings/webhooks`).

<Info>
  **Time to complete:** \~15 minutes  ·  **Difficulty:** Advanced  ·  You need a
  [role](/getting-started/glossary#role) that can manage webhooks.
</Info>

## Create a webhook

<Steps>
  <Step title="Add an endpoint">
    Go to **Settings → Webhooks → New** and enter your **Endpoint URL** (HTTPS), a
    **Label**, and an optional description.
  </Step>

  <Step title="Subscribe to events">
    Pick the events you want to receive (see below). You can also add custom headers.
  </Step>

  <Step title="Enable signing">
    Keep **Sign payloads** on. On save, your **signing secret** is shown once — copy
    it to verify deliveries.
  </Step>
</Steps>

## Events you can subscribe to

<AccordionGroup>
  <Accordion title="Contacts & segments">
    `contact.created`, `contact.updated`, `contact.deleted`, `contact.tags_changed`,
    `contact.opted_in`, `contact.opted_out`, `segment.created`, `segment.updated`,
    `segment.deleted`
  </Accordion>

  <Accordion title="Campaigns & polls">
    `campaign.created`, `campaign.updated`, `campaign.paused`, `campaign.resumed`,
    `campaign.cancelled`, `poll.created`, `poll.closed`, `poll.expired`
  </Accordion>

  <Accordion title="Inbox & messaging">
    `inbox.message.created`, `inbox.message.status_changed`,
    `inbox.conversation.created`, `inbox.conversation.read`, `inbox.unified.assigned`,
    `inbox.note.created`, `inbound.message.persisted`
  </Accordion>

  <Accordion title="Channels & links">
    `sms_channel.connected`, `sms_channel.disconnected`, `sms_channel.provider_switched`,
    `sms_channel.brand_registered`, `sms_channel.brand_deleted`,
    `sms_channel.campaign_created`, `sms_channel.campaign_deleted`,
    `sms_channel.phone_number_purchased`, `join-link.submitted`, `short-link.clicked`
  </Accordion>
</AccordionGroup>

## Verify signatures

Signed deliveries include these headers:

```http theme={null}
X-Autocampaign-Signature: t=<unix>,v1=<hex-hmac-sha256>
X-Autocampaign-Timestamp: <unix>
X-Autocampaign-Event: <event.name>
X-Autocampaign-Delivery: <delivery-id>
```

Compute an HMAC-SHA256 of `<timestamp>.<raw-body>` using your signing secret and
compare it (in constant time) to `v1`. Reject stale timestamps.

## Deliveries and retries

* Failed deliveries retry up to **3 attempts** (after \~1 and \~5 minutes), then
  are set aside as failed (dead-lettered).
* An endpoint that fails repeatedly is **auto-disabled** — re-enable it after fixing.
* View the **delivery log** with status, payload, and response, and **retry** failed
  deliveries manually.
* Use **Send test** to fire a sample event and inspect it.

## FAQ

<AccordionGroup>
  <Accordion title="Can I use HTTP (not HTTPS)?">
    Endpoints must be HTTPS. Private, loopback, and internal addresses are blocked for
    security.
  </Accordion>

  <Accordion title="How do I rotate the signing secret?">
    Use the endpoint's rotate-secret action; the new secret is shown once.
  </Accordion>

  <Accordion title="What if my endpoint is down?">
    Deliveries retry a few times, then are set aside as failed (dead-lettered).
    Persistent failures auto-disable the endpoint until you re-enable it.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Signature verification fails">
    Sign `<timestamp>.<raw-body>` (the exact raw bytes, before JSON parsing) with your
    secret using HMAC-SHA256, and compare to the `v1` value in `X-Autocampaign-Signature`.
  </Accordion>

  <Accordion title="My endpoint was auto-disabled">
    It hit repeated final failures (ones that won't be retried). Fix the endpoint,
    then re-activate it — this resets the failure streak.
  </Accordion>
</AccordionGroup>

<Card title="API reference" icon="code" href="/api/introduction">
  Explore the full API.
</Card>