Trigger an inbound webhook

Start the automation configured behind this trigger URL.

The request body becomes the automation's input. A JSON body is parsed and delivered as input_data.webhook.payload; anything else is delivered as {"raw": "<text>"}. Validate and restrict what the sending system can put there, because the content is supplied to the configured automation.

Run policies come only from the authenticated inbound-webhook configuration. When its require_artifact option is enabled, the run must publish a committed artifact and pass the required artifact_requirement verification check. A sender cannot enable, disable, or override that policy through the request body; even a payload key named require_artifact remains under input_data.webhook.payload.

A 202 means the event was accepted, not that the work finished: the response carries the accepted event, never a run result. Observe the outcome through the runs endpoints or an outbound webhook.

Retries may carry an idempotency id in Idempotency-Key, X-Idempotency-Key, or webhook-id. A retry presenting the same id adopts the event already accepted — the same 202 with the same event id, without consuming a rate or queue slot — instead of starting a second run. Presenting the same id with a different payload is a sender bug rather than a retry, and answers 409.

Each webhook has a limit on accepted events waiting to start (100 by default). When that queue or the per-minute rate window is full, new events receive 429 with Retry-After: 60 before acceptance. Retry after that delay with the same idempotency key and payload. Already accepted events are not evicted by overflow, and their retries still receive the original acknowledgment at capacity. This queue excludes executing runs and runs paused for approval.

An unknown webhook and a bad token are deliberately indistinguishable: both answer 404. A valid token for a paused webhook answers 410, so a sender can tell disabled from wrong URL. Oversized bodies answer 413.

Required access

Credential: trigger token

Authenticated by the token in the URL path, not by a bearer credential. Send no Authorization header. The token is a secret: anyone holding the URL can start the configured work, so treat it like a key and rotate it if it is disclosed.

Path Parameters

Any JSON object. The payload is passed through to the automation unvalidated, so constrain it at the sender.

Response Body

curl -X POST "https://example.com/api/v1/hooks/497f6eca-6276-4993-bfeb-53cbbbba6f08/whk_3f8a1c2e5b7d9046a1c3e5b7d9046a1c" \  -H "Content-Type: application/json" \  -d '{    "event": "deployment.failed",    "service": "checkout",    "commit": "9f2c1ab"  }'

{}