# Webhooks

> Set up a webhook so your server is called whenever published content changes, send a test message and pause, change or remove the address.

A webhook sends a short message to your own server whenever the published content of a project changes, so your website or app can refresh without checking the API all the time. This page shows owners and developers how to set one up in the web app. The message format and how to check its signature are in [Webhook events](https://spatibase.com/docs/reference/webhook-events/).

## Who can set up a webhook?

Owners and developers of a project can set up its webhook, on the **Webhooks** page of the project's **API**. Editors do not see the page. Each project has one webhook address.

## How do I set up a webhook?

1. Open the project's **API** and go to **Webhooks**.
2. Under **Address that receives the messages**, enter your server's address. It must start with `https://`.
3. Select **Add webhook**.
4. Select **Copy** under **Copy your signing secret now** and store the secret on your server. It is shown in full only now. When it is saved, select **I have saved it, hide it**. Afterwards the page shows only the start of the secret.
5. Select **Send test message** to check that your server receives it.

The signing secret starts with `whsec_`. Your server uses it to check that a message really comes from Spatibase. Anyone who has the secret can pretend to be Spatibase, so keep it private.

## What does the webhook send?

Spatibase sends one message each time something changes in the live content:

| In the web app | Sent when |
|---|---|
| **Entry published** | One or more entries went live or changed at a **Publish**, or came back when you went back to an earlier version. |
| **Entry unpublished** | One or more entries came off the API at a **Publish** (or by going back). |
| **Entry deleted** | One or more entries were removed at a **Publish** and moved to the trash, or an entry that was never live was deleted. |
| **Group changed** | The live groups changed at a **Publish** (a group was created, renamed or deleted, or its entries or their order changed), or by going back. |
| **Test message** | You selected **Send test message**. |

Messages are sent when the change goes live, not when someone edits: one **Publish** sends one message per kind, and editing a group or marking entries ready sends nothing until then. A message holds only ids, the project's content version and, for a publish or going back, the [version](https://spatibase.com/docs/publish/versions/) number, not the content itself. Your server then reads what changed from the [Content Delivery API](https://spatibase.com/docs/reference/delivery-api/). Saving a draft sends nothing, because drafts are not live.

## How do I check that messages arrive?

**Recent messages** lists the latest 10 deliveries with **When**, **What happened**, **Result** and the number of **Tries**. The result is **Delivered**, **Failed** (with the reason underneath, such as "The receiver answered with status 500") or **Sending**. Select **Refresh** to update the list. Spatibase keeps the last 50 deliveries per project.

## How do I pause, change or remove the webhook?

- **Pause:** switch **Send messages** off and select **Save changes**. The webhook stays set up but sends nothing until you switch it back on.
- **Change the address:** edit **Address that receives the messages** and select **Save changes**.
- **New secret:** select **New secret** and confirm. The old secret stops working at once, so update your server first, or pause the webhook while you switch.
- **Remove:** select **Remove webhook** and confirm. Spatibase stops sending and forgets the secret and the list of recent messages.

## What are the limits?

- **5 seconds to answer.** Your server must answer with a success status (2xx) within 5 seconds. Anything else, a timeout or a redirect counts as a failure.
- **Up to 3 tries.** A failed message is tried up to 3 times in total, after 1 second and then after 10 seconds. The same message can arrive more than once, so make your handler safe to run twice. A test message is sent once, without retries.
- **Retries can be lost.** Retries that are still waiting are lost if the Spatibase server restarts. Do not rely on webhooks alone: also compare the content version with the last one you saw now and then.
- **Some changes send nothing.** No message is sent for restoring from the trash, imports, changes to images and files, or changes to the content model. If your site depends on those, check the content version too.
- **Public addresses only.** The address must use `https://`, cannot contain a user name or password, and cannot point to a private or local network.

## Related

- [Webhook events and signatures](https://spatibase.com/docs/reference/webhook-events/)
- [Drafts and publishing](https://spatibase.com/docs/publish/draft-and-published/)
- [Access and API keys](https://spatibase.com/docs/publish/access-and-keys/)
- [Content Delivery API reference](https://spatibase.com/docs/reference/delivery-api/)