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

# Subscribe to webhooks

> Create a webhook subscription for an integration and verify the receiving address.

With a webhook subscription, Bottari sends a POST to your address when something the integration can read changes. The body has no content, only IDs and the kind of change. Your server calls the API with those IDs to read the latest values.

Each integration has one subscription. If you need two addresses, create two integrations. Only team owners can manage subscriptions.

## Create a subscription

**1. Prepare your server**

Make sure your address answers POST requests with a 2xx and that you can read `verification_token` from the body. [Verify signatures](https://developers.bottari.ai/webhooks/signature.md) has an example.

**2. Create the subscription**

Under **Webhook** on the integration's page, below **Connected databases**, select **Create subscription**. Enter the **Receiving address** and choose **Events to receive**. All events start selected, and the API version is fixed at `2026-03-11`.

To receive `comment.*` events, also turn on **Read comments** under **Capabilities**.

**3. Receive the verification token**

Bottari sends the verification token to that address in a POST.

```http theme={null}
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: bottari-integration/1.0
x-bottari-signature: sha256=...

{"verification_token":"bts_..."}
```

If your server received the token, you can verify even if it answered with something other than a 2xx.

**4. Enter the token in the app**

Select **Verify** and enter the token. When the status changes to **On · API version 2026-03-11**, changes made from then on send events. Changes made before verification don't.

**5. Store the token**

Add the verification token to your server's environment.

> [!WARNING]
>
> The verification token is the key for verifying signatures. It never appears again in the app or the API.

## Before verification

| Action | Behavior |
| - | - |
| **Send token again** | Sends the same token. Limited to 10 per hour per subscription. |
| Change the address | Creates a new token and sends it to the new address. The old token no longer works. |

A wrong token shows **That token doesn't match.**

## After verification

| Action | Behavior |
| - | - |
| Edit events | Available at any time. |
| Change the address | Locked. Delete the subscription and create a new one. |
| **Pause**, **Resume** | Changes made while paused aren't sent, even after you resume. Events waiting to be sent are dropped. |
| **Delete subscription** | Even the same address has to be verified again. |

If you lose a verified token, delete the subscription and create a new one. Deleting an integration also deletes its subscription.

**Failed deliveries** on the integration's page shows the failure count and the last failure time. See [Retries and automatic pause](https://developers.bottari.ai/webhooks/retries.md).

## Receiving address rules

* Only `https` is accepted.
* Up to 2,048 characters.
* It has to be a public address. Hosts that resolve to a private address are rejected.
* It can't include a username or password, such as `https://user:pass@example.com`.
* Hosts that can't be resolved are rejected.
* Redirects aren't followed. A 3xx counts as a failure.

## Read back after an event

IDs in an event match what the API returns, so you can read them directly.

| Event value | Endpoint |
| - | - |
| `entity.id` (`page`) | `GET /v1/pages/{id}` |
| Property ID in `updated_properties` | `GET /v1/pages/{id}/properties/{property_id}` |
| Block ID in `updated_blocks` | `GET /v1/blocks/{id}` |
| `entity.id` (`data_source`) | `GET /v1/data_sources/{id}` |
| `entity.id` (`database`) | `GET /v1/databases/{id}` |
| `entity.id` (`comment`) | `GET /v1/comments/{id}` |

A trashed row returns 200 with `in_trash: true`. A deleted block's ID from `updated_blocks` returns 404.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.