Appearance
Webhooks API Reference
OneHazel has two kinds of webhook:
- Inbound: an external system POSTs to a OneHazel URL and a workflow runs. This is the Webhook Trigger node.
- Outbound: OneHazel POSTs events to a URL you subscribe, signed so you can verify them.
Inbound: workflow webhooks
Endpoint
POST https://api.onehazel.com/webhook-receiver/wh_<id>Each Webhook Trigger node in a workflow has its own wh_<id> URL, shown in the node's config drawer. Paste it into the sending system's webhook settings. The workflow must be saved and Active.
Authentication: none required. The sending system calls the URL directly. Optionally set a Verification Secret on the trigger to require a signature (below).
Signature verification
When the trigger has a Verification Secret, every request must carry:
X-OneHazel-Signature: <hex HMAC-SHA256 of the raw request body, keyed by the secret>Requests without a matching signature are rejected with 401 and the workflow does not run.
Deduplication
Send an X-Request-Id header with each delivery. A retry that reuses the same id is acknowledged but does not run the workflow again.
Responses
| Status | Meaning |
|---|---|
202 | Accepted, the workflow runs in the background. Check the workflow's Runs tab. |
401 | Signature missing or wrong (only when a Verification Secret is set). |
404 | No active workflow owns this wh_<id>. |
429 | Too many requests from your IP. |
410 | The address is not a workflow webhook (see below). |
To return a custom status or body instead of 202, add a Respond to Webhook node. Full trigger reference: Webhook Trigger.
Retired: /webhook-receiver/<connectionId>
Earlier versions of these docs described a per-connection address, /webhook-receiver/<connectionId>, with provider-specific signature checks. That address never verified incoming requests and has been retired: it now answers 410 Gone and stores nothing. Use a workflow webhook (wh_<id>) instead.
Outbound: signed deliveries
Subscribe a URL under Connect → Webhooks (or POST /webhooks). The signing secret is shown once, when you create the subscription.
Each delivery is a POST with a JSON body and these headers:
| Header | Value |
|---|---|
X-OneHazel-Signature | sha256=<hex HMAC-SHA256 of the raw body, keyed by your signing secret> |
X-OneHazel-Event | The event type, e.g. entity.created |
X-OneHazel-Delivery | Unique delivery id. Use it to deduplicate |
Verify by recomputing the HMAC over the raw body (before parsing JSON) and comparing in constant time. Retry policy and the deliveries log are configurable per subscription in the same page.
Generated operation reference
Every endpoint on this page also has a generated reference page, built from the published OpenAPI document (openapi.yaml, openapi.json):