/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}AuthChange a webhook endpoint: URL, description, events, on/off.
Only the fields sent change. `enabled: true` (or a new URL) also clears an automatic disable. Switching off cancels queued retries. The secret is unchanged; rotate it with `POST …/rotate-secret`.
Path parameters
workspace_id*string · uuidId of the workspace.
endpoint_id*string · uuidId of the endpoint.
Headers
Idempotency-KeystringOpaque client-generated string (1-256 chars, `[A-Za-z0-9._:-]`) that makes a retry of this request safe for 24 hours. The same key with a different body returns 409 `IDEMPOTENCY_KEY_REUSE`.
Request body
urlstring · uriA new absolute https:// URL on a public host.
Example: "https://api.acme.com/webhooks"
descriptionstringA new label; null clears it.
Example: "Production receiver"
event_typesarrayReplaces the subscription. Event types from `GET …/webhooks/event-types`. Empty or omitted means every event, including types added later.
Example: ["job.succeeded","job.failed"]
enabledbooleanSwitch it on or off. Switching on also clears an automatic disable.
Example: true
Response · 200
id*string · uuidThe endpoint's id.
scope_type*stringWhat owns the endpoint: `workspace`, `app` or `community`.
Example: "workspace"
scope_id*stringId of the owning workspace, app or community.
url*string · uriWhere events are sent.
Example: "https://api.acme.com/webhooks"
description*stringA label for people; null when unset.
Example: "Production receiver"
event_types*arraySubscribed event types. Empty means every event, including types added later.
Example: []
enabled*booleanThe on/off switch (`PATCH … { enabled }`).
status*object`enabled` receives events. `disabled` was switched off. `auto_disabled` was switched off after 20 failed deliveries in a row or 24 hours of failures; `PATCH { enabled: true }` turns it back on.
disabled_at*string · date-timeWhen it was switched off; null while enabled.
disabled_reason*object`manual`: switched off by a caller. `failing`: switched off automatically after failed deliveries. Null while enabled.
consecutive_failures*numberFailed automatic deliveries in a row; a success resets it.
first_failure_at*string · date-timeStart of the current failure streak.
signing_secret_hint*stringLast 4 characters of the signing secret.
Example: "x9Q="
prev_signing_secret_active*booleanTrue while the previous secret still signs too (after a rotation, for its grace period).
prev_signing_secret_expires_at*string · date-timeUntil then the previous secret signs too (after a rotation).
legacy_signature*booleanTrue for endpoints carried over from the product's previous webhook system: they also receive the old signature header until its sunset date.
created_at*string · date-timeWhen the endpoint was created.
updated_at*string · date-timeWhen the endpoint last changed.
Example
Request
PATCH https://api.trawl.productcraft.co/v1/workspaces/{workspace_id}/webhooks/endpoints/{endpoint_id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"url": "https://api.acme.com/webhooks",
"description": "Production receiver",
"event_types": [
"job.succeeded",
"job.failed"
],
"enabled": true
}Response
{
"id": "00000000-0000-0000-0000-000000000000",
"scope_type": "workspace",
"scope_id": "string",
"url": "https://api.acme.com/webhooks",
"description": "Production receiver",
"event_types": [],
"enabled": false,
"status": {},
"disabled_at": "2026-01-01T00:00:00.000Z",
"disabled_reason": {},
"consecutive_failures": 0,
"first_failure_at": "2026-01-01T00:00:00.000Z",
"signing_secret_hint": "x9Q=",
"prev_signing_secret_active": false,
"prev_signing_secret_expires_at": "2026-01-01T00:00:00.000Z",
"legacy_signature": false,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}