> For the complete documentation index, see [llms.txt](https://docs.multiset.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multiset.ai/fundamentals/rest-api-docs/webhooks.md).

# Webhooks

Register and manage the endpoint MultiSet delivers lifecycle events to, send test events, rotate the signing secret, and read the delivery log.

These endpoints manage the HTTPS URL that map, map set, and object lifecycle events are delivered to. See [Webhooks](/fundamentals/credentials/webhooks.md) for the event catalogue, the payload envelope, signature verification, and the retry policy.

{% hint style="warning" %}
To whitelist your domain, follow: [Configuring Allowed Domains (CORS)](/fundamentals/credentials/configuring-allowed-domains-cors.md)
{% endhint %}

{% hint style="info" %}
**One endpoint per account.** Registering a second returns `409`. Update or delete the existing one instead.

Endpoint management requires the **Write** scope, deleting requires **Delete**, and the delivery log requires **Query**. See [Credentials](/fundamentals/credentials.md).
{% endhint %}

## Endpoints

### Register a webhook endpoint

Registers the URL events are delivered to, and verifies it immediately by POSTing a signed `endpoint.verify` challenge that your service must echo back. See [Verifying your endpoint](/fundamentals/credentials/webhooks.md#verifying-your-endpoint).

The signing secret is returned **once**, in this response. It cannot be read back afterwards, only rotated.

**Constraints:**

* The account must not already have an endpoint.
* `url` must be HTTPS in production, and must not resolve to a private, loopback, or link-local address.
* Every entry in `events` must be a known event type or a valid wildcard.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint" method="post" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

{% hint style="warning" %}
A `201` does not by itself mean events will flow. Check `verified` in the response: if the challenge failed, the endpoint is created but sits in `pending_verification` and **no events are delivered** until it passes. `verificationError` says why.
{% endhint %}

### Get the account's webhook endpoint

Returns the registered endpoint, including its `status`, `consecutiveFailures`, and `lastSuccessAt`, or `null` if none is registered. The signing secret is never returned.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint" method="get" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Update a webhook endpoint

Change the URL, the subscribed events, the description, or set `isActive` to `false` to stop delivery without deleting the endpoint. Send at least one field.

{% hint style="warning" %}
**Changing `url` resets the endpoint to `pending_verification`.** Delivery stops until the new URL passes the challenge. Changing only `events` or `description` does not affect verification.
{% endhint %}

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint/{id}" method="put" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Delete a webhook endpoint

Removes the endpoint. Delivery stops immediately. The delivery log is kept, so you can still audit what was sent before the endpoint was removed.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint/{id}" method="delete" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Re-run endpoint verification

Re-sends the signed challenge. Use it after fixing a receiver whose first verification failed, or to re-enable an endpoint that was auto-disabled after 20 consecutive delivery failures.

A successful verification sets the endpoint back to `active` and resets `consecutiveFailures` to zero, so this is the self-service route out of an auto-disable.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint/{id}/verify" method="post" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Send a test event

Delivers a signed sample event synchronously and reports what your endpoint answered: the response code, how long it took, and the first 2KB of the response body. Pass `type` to choose which event shape to simulate, or omit it for `map.active`.

Test events carry `livemode: false`, are never retried, do not count towards `consecutiveFailures`, and are recorded in the delivery log with `isTest: true`.

{% hint style="info" %}
This call returns `200` even when delivery failed, because the API call itself succeeded. Read `delivered` to find out whether your endpoint accepted the event.
{% endhint %}

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint/{id}/test" method="post" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Rotate the signing secret

Returns a new secret once. The previous secret stops verifying immediately, so deploy the new one first, or accept a short window of signature failures. Failed deliveries in that window are retried, so nothing is lost if you rotate and redeploy promptly.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/endpoint/{id}/rotate-secret" method="post" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### List webhook deliveries

Delivery history for the account. Filter by event `type`, delivery `status`, a date range, or `resourceId` to see every event raised for one map, map set, or object.

The event `payload` is omitted here to keep responses small. Fetch a single delivery to read it.

| `status`    | Meaning                                                       |
| ----------- | ------------------------------------------------------------- |
| `queued`    | Accepted, first attempt not yet made                          |
| `delivered` | Your endpoint returned a `2xx`                                |
| `retrying`  | An attempt failed, another is scheduled at `nextRetryAt`      |
| `exhausted` | All five attempts failed, it will not be tried again          |
| `cancelled` | Not delivered, for example the endpoint was deleted mid-chain |

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/delivery" method="get" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

### Get one delivery

Returns the full record for one event, including the exact `payload` that was sent and one `history` entry per attempt with its response code, error kind, and timing.

{% openapi src="/files/2fMs0Im4kkiWFn7N43aD" path="/delivery/{eventId}" method="get" %}
[webhooks-api.yaml](https://3163433004-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FokTDI7QVY04Zvb1pQ8Ry%2Fuploads%2Fgit-blob-ee922a5b390c3e0a3a00187168f5b2f43828175d%2Fwebhooks-api.yaml?alt=media)
{% endopenapi %}

## Error kinds

When a delivery fails, `errorKind` says how, which is usually enough to tell a configuration problem from an outage:

| `errorKind`        | Cause                                                                         |
| ------------------ | ----------------------------------------------------------------------------- |
| `timeout`          | No response within 10 seconds                                                 |
| `dns`              | The hostname did not resolve                                                  |
| `tls`              | Certificate or handshake failure                                              |
| `conn_refused`     | Nothing listening on the port                                                 |
| `http_4xx`         | Your endpoint rejected the request, a signature check failing looks like this |
| `http_5xx`         | Your endpoint errored                                                         |
| `redirect_refused` | The endpoint returned a redirect, which is never followed                     |
| `network`          | Anything else at the transport layer                                          |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.multiset.ai/fundamentals/rest-api-docs/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.