Receive events
Hooks accepts JSON and form-encoded payloads over HTTPS. It records the raw body and headers before applying verification rules, so you can inspect exactly what arrived.
Request headers
Section titled “Request headers”| Header | Description |
|---|---|
X-Hooks-Signature |
Timestamp and HMAC signature for the raw body. Verify this before processing. |
X-Hooks-Event |
Unique event ID, useful for logging and support. |
X-Hooks-Delivery |
Unique delivery ID. Reuse it as an idempotency key at your destination. |
Content-Type |
application/json or application/x-www-form-urlencoded. |
Provider-specific headers are preserved on the event as well, for example X-GitHub-Event, Stripe-Signature, or Linear-Delivery.
Response behavior
Section titled “Response behavior”Hooks returns 202 as soon as the event is persisted. It does not wait for downstream services.
202 Accepted— the event was stored and queued for fan-out.4xx— the request was rejected and no event was created. Check the endpoint’s verification rules and signature configuration.429— the endpoint’s ingest rate limit was exceeded. HonorRetry-After.
Use the raw request body when computing signatures. Re-serializing JSON can change whitespace and key order, producing a false mismatch.
Body handling
Section titled “Body handling”- JSON bodies are parsed and stored as structured data.
application/x-www-form-urlencodedbodies are parsed into fields; a GitHub-stylepayload=<json>field is unpacked into the embedded JSON.- Any other body is stored as text and is not normalized into structured fields.