Pause a webhook subscription
Sets the webhook's status to paused and removes it from event fan-out, so no events are delivered until you resume it.
Sets the webhook's status to paused and removes it from event fan-out, so no events are delivered until you resume it. The subscription, its events, and its signing secret are all preserved — pausing is reversible and non-destructive, unlike deleting. Pausing does not reset the delivery-failure counters (consecutiveFailures, autoPaused, pausedReason); those clear only on resume, so a paused endpoint keeps its history. Returns the updated webhook. Rate limited to 30 pause and resume calls per hour combined; requires the webhooks:write scope.
Scope: webhooks:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
webhook | string | yes | The webhook's ID. |
Response
200 Success. Body: application/json, Webhook.
| Field | Type | Required | Description |
|---|---|---|---|
object | "webhook" | yes | |
id | string (uuid) | yes | |
url | string (uri) | yes | |
events | array of "message.received", "message.quarantined", "message.sent", "message.delivered", "message.bounced", "message.complained", "message.delayed", "budget.tripped", "compliance.erasure.completed", "object.scanned", "share_link.opened", "letter.status_changed", "domain.verified", "verification.resolved", "verification.expired", "call.status_changed" | yes | |
label | string or null | no | Optional human label for the endpoint, or null when unlabeled. |
status | "active", "paused" | yes | |
createdAt | string (date-time) | yes | |
lastDeliveryAt | string (date-time) or null | no | Timestamp of the most recent successful webhook delivery, or null before the first successful delivery. |
secondarySecretExpiresAt | string (date-time) or null | no | End of the dual-secret window after a rotation, or null. |
secondarySecretActive | boolean | no | Whether deliveries are still signed with the previous secret too. |
consecutiveFailures | integer | no | |
pausedReason | string or null | no | auto:delivery_failures when the circuit breaker paused the endpoint, else null. |
autoPaused | boolean | no | |
autoPausedAt | string (date-time) or null | no |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |