Webhooks — API reference

Signed delivery of events, so you do not have to poll.

GET /v1/webhook-endpoints

List webhook endpoints

Parameters

Name	In	Requirement	Description
`limit`	query	Optional	Page size.
`starting_after`	query	Optional	Cursor from the previous page’s `next_cursor`.

Responses

Status	Description
`200`	A page of endpoints.
`400`	Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

The response contains secret exactly once. It is not retrievable afterwards; rotate the endpoint if you lose it.

Parameters

Name	In	Requirement	Description
`Idempotency-Key`	header	Required	Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409.

Request body

Field	Type	Requirement	Description
`url`	`string` (uri)	Required	Must be HTTPS.
`enabled_events`	array of `job.succeeded` · `job.failed` · `job.cancelled` · `file.ready` · `file.rejected` · `file.deleted` · `file.expired`	Required

Responses

Status	Description
`201`	Registered. Contains the secret.
`400`	Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`409`	Codes: idempotency_conflict, upload_session_consumed, conflict.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

Delete a webhook endpoint

Parameters

Name	In	Requirement	Description
`webhook_endpoint_id`	path	Required	Webhook endpoint identifier.

Responses

Status	Description
`204`	Deleted. No further events are delivered to it.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.

Delivers a signed synthetic event so you can verify your handler before relying on it.

Parameters

Name	In	Requirement	Description
`webhook_endpoint_id`	path	Required	Webhook endpoint identifier.
`Idempotency-Key`	header	Required	Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409.

Responses

Status	Description
`202`	Test event queued for delivery.
`401`	Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query.
`403`	Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted.
`404`	Not found. A resource belonging to another organization returns 404, never 403 — a 403 would confirm it exists. Codes: not_found.
`409`	Codes: idempotency_conflict, upload_session_consumed, conflict.
`429`	Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted.
`500`	Codes: internal_error.
`503`	Codes: processing_unavailable, dependency_unavailable.
`504`	Codes: timeout.