# Webhook endpoints API

> The calls to create, read, change and unsubscribe webhook endpoints, rotate secrets, test, replay and read deliveries.

Last updated: 2026-10-30. Source: https://docs.smartchat.marketing/en/webhooks/endpoints-api/

> **Example values** The secrets (`whsec_...`) in the examples on this page are made-up example values. The real secret is shown **once**, in the answer to the call that creates or rotates an endpoint. Copy it then. It cannot be read again.

These calls manage your outgoing webhooks. Reading needs `webhooks:read`; changing needs `webhooks:write`. Removing an endpoint (unsubscribing) is one of the few removals that keys may do. It removes the endpoint and its delivery log.

- [Create webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/create_webhook_endpoint/): `POST /v1/webhook-endpoints`
- [List webhook endpoints](https://docs.smartchat.marketing/en/api/reference/webhooks/list_webhook_endpoints/): `GET /v1/webhook-endpoints`
- [Get webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/get_webhook_endpoint/): `GET /v1/webhook-endpoints/{endpoint_id}`
- [Update webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/update_webhook_endpoint/): `PATCH /v1/webhook-endpoints/{endpoint_id}`
- [Unsubscribe webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/unsubscribe_webhook_endpoint/): `DELETE /v1/webhook-endpoints/{endpoint_id}`
- [Rotate webhook secret](https://docs.smartchat.marketing/en/api/reference/webhooks/rotate_webhook_secret/): `POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret`
- [Enable webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/enable_webhook_endpoint/): `POST /v1/webhook-endpoints/{endpoint_id}/enable`
- [Test webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/test_webhook_endpoint/): `POST /v1/webhook-endpoints/{endpoint_id}/test`
- [Replay webhook events](https://docs.smartchat.marketing/en/api/reference/webhooks/replay_webhook_events/): `POST /v1/webhook-endpoints/{endpoint_id}/replay`
- [List webhook deliveries](https://docs.smartchat.marketing/en/api/reference/webhooks/list_webhook_deliveries/): `GET /v1/webhook-endpoints/{endpoint_id}/deliveries`
- [Redeliver webhook delivery](https://docs.smartchat.marketing/en/api/reference/webhooks/redeliver_webhook_delivery/): `POST /v1/webhook-deliveries/{delivery_id}/redeliver`

The full description of each call is in the [API reference](https://docs.smartchat.marketing/en/api/reference/webhooks/).

## Test, enable, replay and redeliver

These four calls look alike but behave differently. The table says what must be true first, what each call does, what happens if you repeat it, and whether it takes an `Idempotency-Key`.

| Call | What must be true first | What it does | If you repeat it | Idempotency-Key |
|---|---|---|---|---|
| [Test](https://docs.smartchat.marketing/en/api/reference/webhooks/test_webhook_endpoint/) | The endpoint exists. Its state is not checked. | Sends one signed `webhook.test` event at once and waits for the answer. Writes one line in the delivery log. Does not change the health of the endpoint and is never retried. | Each call sends a new test event with a new delivery ID. A test delivery cannot be redelivered. | Not needed |
| [Enable](https://docs.smartchat.marketing/en/api/reference/webhooks/enable_webhook_endpoint/) | The endpoint exists. Its address must still be allowed (`webhook_url_invalid`) and must not be used by another endpoint that is not disabled (`conflict`). | Sets the state to `active`, clears the reason and resets the failure counter. Events are queued for the endpoint again from now on if it was paused or disabled. | Safe to repeat: the endpoint stays `active`. | Optional |
| [Enable](https://docs.smartchat.marketing/en/api/reference/webhooks/enable_webhook_endpoint/) with `replay_since` | As above. In addition: the time is not in the future and at most 7 days back (`validation_failed`), the key has the read permission for every event type of the endpoint (`insufficient_scope`), and no replay of this endpoint is still running (`conflict`). | As above, and also queues the events since that time for this endpoint (only the types it subscribes to, at most 10,000). The answer has `replay.queued` and `replay.truncated`. | Events that already wait for delivery are not queued twice. While an earlier replay is still running, the call answers `conflict`. | Optional |
| [Replay](https://docs.smartchat.marketing/en/api/reference/webhooks/replay_webhook_events/) | The endpoint is `active` or `degraded` (otherwise `conflict`: enable it first). `since` is not in the future and at most 7 days back (`validation_failed`). The key has the read permission for every event type of the endpoint (`insufficient_scope`). No replay of this endpoint is still running (`conflict`). | Queues the events since `since` for this endpoint (only the types it subscribes to, at most 10,000, events removed for data protection are skipped). Status 202; the deliveries are sent afterwards with the normal retry schedule. | The same Idempotency-Key returns the first answer. Events that already wait are not queued twice. While a replay is still running, a new one answers `conflict`. | Required |
| [Redeliver](https://docs.smartchat.marketing/en/api/reference/webhooks/redeliver_webhook_delivery/) | The delivery belongs to your account and comes from a real event (a test delivery answers `conflict`). The endpoint is `active` or `degraded` (otherwise `conflict`). The event is still in the 30 day log and was not removed for data protection (otherwise `conflict`). The key has the read permission for the event type. | Queues one new delivery of the same event to the same endpoint. Status 202, new delivery ID, state `pending`. | Without a key every call queues one more delivery. The same Idempotency-Key returns the first answer. | Optional |

"Not needed" means the call does not ask for the key. "Safe by nature" or "safe to repeat" is a separate fact: the end state is the same when you repeat the call. See [Idempotency](https://docs.smartchat.marketing/en/concepts/idempotency/).