> ## Documentation index
>
> Fetch the complete documentation index at: https://andesine.app/docs/llms.txt
> Use it to find all pages before you explore further.

# Webhooks

> Get HTTP requests when content changes or is published, and verify them in your server.

Webhooks send an HTTP request to your server when something changes in the workspace. Use them to rebuild a site after a publish, update a search index, or notify a chat.

## Create a webhook

Go to **Settings → API → Webhooks** and create a webhook. You need a role with the **Webhooks** permission.

| Field       | Description                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------- |
| Name        | A name that helps you find the webhook                                                            |
| URL         | The `https` address of your server                                                                |
| Events      | The events that the webhook sends                                                                 |
| Data access | The collections and channels that the webhook reports, and whether it includes restricted content |

After you save, Andesine shows the signing secret (`whsec_...`) once. Store it in your server's secret storage.

![The webhook form with the URL, the selected events, and the data access settings.](https://andesine.app/docs/_andesine/assets/945627befb55dbb73b174aa50f24d8245ab1be918148a2e05929e76b78d2d236.webp)

You can also manage webhooks with the API and the [SDK](https://andesine.app/docs/developers/sdk/) (`client.webhooks`), and send a test event with `webhooks.sendTest`.

## Events

| Event                         | Sent when                                      |
| ----------------------------- | ---------------------------------------------- |
| `entry.created`               | An entry is created                            |
| `entry.updated`               | An entry is renamed or its details change      |
| `entry.content_saved`         | The content of an entry is saved               |
| `entry.moved`                 | An entry is moved                              |
| `entry.deleted`               | An entry is deleted                            |
| `entry.restored`              | A deleted entry is restored                    |
| `collection.created`          | A collection is created                        |
| `collection.updated`          | A collection is renamed or its settings change |
| `collection.moved`            | A collection is moved                          |
| `collection.deleted`          | A collection is deleted                        |
| `collection.restored`         | A deleted collection is restored               |
| `publishing.channel_advanced` | New content is published to a channel          |
| `publishing.channel_created`  | A channel is created                           |
| `publishing.channel_deleted`  | A channel is deleted                           |

To rebuild a site after each publish, use `publishing.channel_advanced`.

Each event has an `id`, a `type`, the time (`occurredAt`), the `workspaceID`, a `subject` (the entry, collection, or channel that changed), the event `data`, and an `actor`: the member, API key, extension, or app that made the change, or `null` for changes by Andesine.

## Verify requests

Each request is signed with your secret. Always verify the signature before you use the event. With the SDK:

```ts
import { verifyWebhookRequest } from "@andesine/sdk/webhooks";

export async function POST(request: Request): Promise<Response> {
  try {
    const event = await verifyWebhookRequest(request, { secret: process.env.ANDESINE_WEBHOOK_SECRET! });

    if (event.type === "publishing.channel_advanced") {
      // Start a site build.
    }

    return new Response(null, { status: 204 });
  } catch {
    return new Response(null, { status: 400 });
  }
}
```

The signature covers the `webhook-id` and `webhook-timestamp` headers and the raw body, with HMAC-SHA256. The signature is in the `webhook-signature` header, in the form `v1,<signature>`. Verify the raw body, not parsed JSON. Requests older than five minutes are rejected.

## Deliveries and retries

- Return a `2xx` status quickly, and do slow work in the background.
- If your server does not return `2xx`, Andesine tries again later, with longer delays between attempts. After repeated failures, it disables the webhook. Fix the server and enable the webhook again.
- An event can arrive more than once, and events can arrive in any order. Use the event `id` to skip duplicates.
- Events tell you that something changed. Read the current state from the API when you need it.

Select **See events** on a webhook to see its deliveries, their responses, and to send an event again.

## Rotate the secret

Select **Rotate secret** and choose when the old secret stops working: now, or after 24 hours. During the 24 hours, Andesine signs requests with both the old and the new secret, so you can update your server without missing events.