Webhook-Endpunkte API
Diese Aufrufe verwalten deine ausgehenden Webhooks. Lesen braucht webhooks:read; Ändern braucht webhooks:write. Einen Endpunkt zu entfernen (abzumelden) ist eine der wenigen Entfernungen, die Schlüssel tun dürfen. Es entfernt den Endpunkt und sein Zustellprotokoll.
- Create webhook endpoint:
POST /v1/webhook-endpoints - List webhook endpoints:
GET /v1/webhook-endpoints - Get webhook endpoint:
GET /v1/webhook-endpoints/{endpoint_id} - Update webhook endpoint:
PATCH /v1/webhook-endpoints/{endpoint_id} - Unsubscribe webhook endpoint:
DELETE /v1/webhook-endpoints/{endpoint_id} - Rotate webhook secret:
POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret - Enable webhook endpoint:
POST /v1/webhook-endpoints/{endpoint_id}/enable - Test webhook endpoint:
POST /v1/webhook-endpoints/{endpoint_id}/test - Replay webhook events:
POST /v1/webhook-endpoints/{endpoint_id}/replay - List webhook deliveries:
GET /v1/webhook-endpoints/{endpoint_id}/deliveries - Redeliver webhook delivery:
POST /v1/webhook-deliveries/{delivery_id}/redeliver
Die volle Beschreibung jedes Aufrufs steht in der API-Referenz.
#Testen, aktivieren, erneut abspielen und erneut zustellen
Diese vier Aufrufe sehen ähnlich aus, verhalten sich aber verschieden. Die Tabelle sagt, was zuerst gelten muss, was jeder Aufruf tut, was bei einer Wiederholung passiert und ob er einen Idempotency-Key nimmt.
| Call | What must be true first | What it does | If you repeat it | Idempotency-Key |
|---|---|---|---|---|
| Test | 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 | 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 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 | 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 | 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" heißt, dass der Aufruf den Key nicht verlangt. "Safe by nature" oder "safe to repeat" ist ein eigener Fakt: Der Endzustand ist gleich, wenn du den Aufruf wiederholst. Siehe Idempotency.