Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

Management API authentication for /api/* endpoints. Use the Authorization header with Bearer <API key>. Virtual keys, dashboard/user/session tokens, and x-api-key headers are not supported on management APIs.

Body

application/json

Create or update body for a webhook endpoint. The signing secret is never accepted here — it is generated by the server and returned once at creation, and can only be changed through the rotate-secret endpoint.

name
string
required

Unique endpoint name.

url
string
required

Delivery URL. HTTPS is required unless allow_private_network is set.

events
enum<string>[]
required

Events this endpoint subscribes to.

A terminal async-job event a webhook endpoint can subscribe to:

  • async_job.completed: an async job finished successfully
  • async_job.failed: an async job finished with an error
Available options:
async_job.completed,
async_job.failed
headers
object

Custom headers sent with every delivery. Values support env var syntax ("env.MY_VAR") and are encrypted at rest. Reserved delivery headers (webhook-id, webhook-timestamp, webhook-signature, content-type, etc.) cannot be overridden.

include_response
boolean
default:false

Inline the job response into delivery payloads, capped by max_response_payload_kbs.

allow_private_network
boolean
default:false

Permit private-network receivers and plain http. Link-local and metadata addresses stay blocked.

disabled
boolean
default:false

Register the endpoint without delivering to it.

max_retries
integer

Retries after the first failed attempt (default 4). 0 selects the default.

Required range: x >= 0
retry_backoff_initial_seconds
integer

Delay before the first retry; each further retry doubles it (default 30). 0 selects the default.

Required range: x >= 0
retry_backoff_max_seconds
integer

Cap on the per-retry delay (default 1800). 0 selects the default.

Required range: x >= 0
attempt_timeout_seconds
integer

End-to-end bound for one delivery attempt (default 10). 0 selects the default.

Required range: x >= 0
max_response_payload_kbs
integer

Cap for inlined response payloads in KB when include_response is set (default 256). 0 selects the default.

Required range: x >= 0
max_concurrent_deliveries
integer

Concurrent in-flight deliveries to this endpoint per node (default 10). 0 selects the default.

Required range: x >= 0

Response

Endpoint created; signing secret returned once.

Returned once when an endpoint is created or its secret is rotated. The secret is shown a single time and cannot be retrieved again.

endpoint
object

A registered webhook endpoint. The signing secret is never included in this representation; custom header values are redacted.

secret
string

The signing secret in whsec_ format. Store it now; it is never returned again.