# Webhooks

> A webhook in MailCamp is an HTTPS endpoint of yours that MailCamp calls with a POST request when a selected event happens in your account — a new subscriber, an unsubscribe, a campaign open. Webhooks push events to your systems; the API lets you pull data on demand.

## What it is

Where an API token is used by your application to ask MailCamp for data, a webhook is MailCamp telling your application that something happened, as it happens. Typical uses are syncing subscription changes back into a CRM, triggering an internal workflow on signup, or logging engagement in a data warehouse.

## Key concepts

- **URL**: the endpoint MailCamp posts to. One webhook has one URL and one set of events.
- **Events**: which occurrences trigger the call. Events are grouped as **Subscribers**, **Campaigns**, **Tags** and **Mailing lists**, and a webhook can subscribe to any combination.
- **Secret**: a key shown once on the webhook, used to verify and decrypt the payload it receives. Treat it as a credential and never expose it client-side.
- **Status**: `Active` (events are delivered), `Inactive` (set by you; nothing is delivered), `Disabled` (set by MailCamp after repeated failures or long inactivity — set the status back to active to resume).
- **Requests**: every delivery attempt is logged per webhook, with its event and payload, so a failed integration can be inspected after the fact.

## Available events

Subscribers: created, subscribed, unsubscribed, bounced, updated, deleted, email changed, topics updated, campaign sent, campaign opened, campaign link clicked.

Campaigns: created, updated, deleted.

Tags: created, updated.

Mailing lists: created, updated.

## Common workflows

### Creating a webhook

1. Open **Settings → Webhooks**.
2. Choose **Create a new webhook** and give it a name and the endpoint URL of your application.
3. Select the events that should trigger it.
4. Save, then copy the secret and store it in your application.
5. Verify delivery under the webhook's **Requests**, which shows the event and payload of each call.

### Recovering a disabled webhook

A webhook that keeps failing, or that goes unused for a long time, is set to `Disabled`. Fix the endpoint, then edit the webhook and set its status back to `Active`.

## Limits and edge cases

- Delivery is per event, not batched; a campaign sent to many recipients produces many calls if you subscribe to per-recipient events such as campaign opened.
- Your endpoint should answer quickly and do its work asynchronously; slow endpoints are what eventually get a webhook disabled.
- Changing the events on an existing webhook does not replay past events — only future ones are delivered.

## Web routes

Paths use `:id` as the placeholder for a webhook's identifier.

- `/admin/webhooks` — webhook overview.
- `/admin/webhooks/new` — create a webhook.
- `/admin/webhooks/:id` — webhook detail, including its secret.
- `/admin/webhooks/:id/update` — edit URL, events, or status.
- `/admin/webhooks/requests/:id` — delivery log for one webhook.

## Related

- [API tokens](/llms/api-tokens.txt) — the pull counterpart of webhooks.
- [Contacts](/llms/contacts.txt) — the subject of most subscriber events.
- [Statistics](/llms/statistics.txt) — aggregate reporting on the same events.