Delete a webhook subscription
Delete one subscription permanently.
Delete one subscription permanently.
This removes the row: the URL, the headers, the signing secret and the event
list all go with it. To stop deliveries reversibly, PATCH enabled: false
instead — everything is kept and one more PATCH turns it back on.
Delivery ledger rows already written are NOT removed; they remain readable
under GET /v2/webhooks/deliveries until their 30-day expiry, so a
post-mortem survives the subscription it describes.
Deleting an agent's last subscription makes that agent fall back to the organisation-wide default, if one exists.
An unknown id and an id belonging to another organisation both answer 404. Deleting twice therefore answers 204 then 404.
A change takes effect within 60 seconds.
Errors: 400, 401, 403, 404, 422, 429, 503.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/webhooks/{subscription_id}Authorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Path Parameters
subscription_idRequiredSubscription Id
The subscription_id returned on create.
Query Parameters
organization_idOrganization Id
Must match the organisation the API key belongs to.
Response Body
400
1000 — malformed input the schema could not reject: an unknown event type, a method other than POST/PUT, a reserved header name, or a callback_url pointing at a private, loopback or metadata address.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of a gat_ key.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
404
1200 — no such subscription or delivery in this organisation. Cross-tenant reads answer 404, never 403.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — per-organisation rate limit exceeded. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — webhook subscriptions are temporarily unavailable; retry.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
504
1502 — a service this endpoint depends on did not respond in time.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
Empty. The subscription is gone.