Skip to main content
PATCH
Update a webhook
  • Only its creator can change it; another member’s is forbidden.
  • A webhook turns itself off when its receiver answers 410 or fails 20 deliveries in a row. Setting status to active turns it back on and clears its failures.
  • Callers: an API key, an MCP OAuth token or a Dashboard session.
  • Permission: jobs:read.
  • Effect: Creates or changes something.
  • Errors: not_found, webhooks_unavailable, and the errors any request can get.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required

a webhook ID: wh_ and 32 lowercase hex digits

Example:

"wh_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

Body

application/json
url
string
events
enum<string>[]

an array of at least 1 item(s)

Minimum array length: 1
Available options:
job.needs_input,
job.input_expiring,
job.succeeded,
job.failed,
job.repairing
status
enum<string>

active turns a disabled webhook on again and clears its failures; disabled turns it off

Available options:
active,
disabled

Response

The changed webhook

id
string
required

a webhook ID: wh_ and 32 lowercase hex digits

Example:

"wh_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

created_by
object
required

The member who made the webhook. Only they can change, test or rotate it, and it carries events for the jobs they can see

url
string
required
events
enum<string>[]
required
Available options:
job.needs_input,
job.input_expiring,
job.succeeded,
job.failed,
job.repairing
status
enum<string>
required
Available options:
active,
disabled
disabled_reason
enum<string> | null
required

Why a disabled webhook sends nothing: manual (turned off), gone (its receiver answered 410), unreachable (20 failed deliveries in a row) or secret_unreadable (rotate its secret)

Available options:
manual,
gone,
unreachable,
secret_unreadable
created_at
string
required

a string to be decoded into a Date

last_delivery_at
string | null
required

a string to be decoded into a Date