Delete a webhook
DELETE /v1/webhooks/{webhook_id}
Read as Markdown ↗DELETE /v1/webhooks/{webhook_id}
Requires an API key: Authorization: Bearer YOUR_CREDENTIAL.
Deletes the webhook. status: "deleted" means the provider endpoint is gone; "pending" means removal was recorded and will be completed in the background, during which the webhook reads as pending and can be deleted again safely.
Deletion stops future delivery and is the only way to change a URL: add the replacement first if you need continuity. The ID is never reused. Missing and other-account webhooks return 404. Delivery history for the deleted webhook is no longer readable through its ID; the event view still lists its past attempts with a null webhook_id.
Parameters
| Parameter | Location | Required | Type | Meaning |
|---|---|---|---|---|
webhook_id | path | Yes | string | Owned Cherami resource ID returned by the API. |
curl example
Replace resource-ID placeholders with returned IDs. Supply CHERAMI_API_KEY through your private shell environment.
curl --silent --show-error --include --request DELETE \
"https://cherami.to/v1/webhooks/WEBHOOK_ID" \
--header "Authorization: Bearer $CHERAMI_API_KEY"Responses
HTTP 200
Successful operation; inspect resource state and outcome fields.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
{
"id": "11111111-1111-4111-8111-111111111111",
"status": "deleted"
}HTTP 401
unauthorized: Provide a valid bearer credential. Use human-approved recovery if access is lost.
X-Request-ID: Support correlation ID, not an idempotency key.WWW-Authenticate:"Bearer"
Content type: application/json.
HTTP 404
not_found: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 409
webhook_operation_in_progress: Another change to this webhook is in flight. Retry after a minute; read the webhook first if an earlier change was uncertain.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
HTTP 503
webhooks_unavailable: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate.
X-Request-ID: Support correlation ID, not an idempotency key.
Content type: application/json.
Schema: WebhookDeletion
deleted: the provider endpoint is gone. pending: removal is recorded and finishes in the background; the webhook no longer delivers new work once removed at the provider.
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
id | Yes | string | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
status | Yes | "deleted" or "pending" |
Schema: Error
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
error | Yes | object |
error fields
| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
code | Yes | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
message | Yes | string | Human-readable context, not a stable string to match. |
HTTP conventions, errors and pagination · Download OpenAPI 3.1