Skip to main content
Webhooks push platform events to your server the moment they happen, a message is delivered, a contact is created, an automation completes, so your backend can react without polling. This guide is the receive side: subscribe, verify the signature, return 200.
In plain terms. Instead of your server constantly asking “anything new?”, Onchain Suite calls your server the moment something happens, more like a doorbell than checking the door every minute. Your job is to answer, confirm it’s really us (the signature check), and reply 200.
This is the inverse of custom events. Custom events go from your product into the platform; webhooks come from the platform to your endpoint.

Quickstart

Verify every delivery in a few lines. The signature is an HMAC-SHA256 of timestamp.rawBody, keyed with the whsec_… secret shown once when you create the endpoint.
Verify against the raw request body, not a re-serialized copy. express.json() or any middleware that parses and re-stringifies the JSON will reorder or reformat it and the signature will never match. Read the raw bytes, verify, then parse. The delivered body’s key order is id, type, createdAt, data.

The delivery

Each event is an HTTP POST to your URL with a JSON envelope:

Headers

The signature, exactly

  • t is the emit time in Unix seconds.
  • v1 is HMAC_SHA256(secret, "<t>.<rawBody>") as a lowercase hex string.
  • secret is the full whsec_… string, used verbatim as the HMAC key (keep the whsec_ prefix).
  • The signed material is the literal t, a period, then the raw body bytes.
To verify: parse t and v1 from the header, recompute the HMAC over `${t}.${rawBody}`, and compare with a constant-time equality check. Optionally reject deliveries whose t is more than a few minutes from now to blunt replays.

The flow

Subscribing

Webhook endpoints are managed from the dashboard (Developers → Webhooks) or via the developer API. Creating, editing, and deleting endpoints requires Owner or Admin.
1

List the available topics

Returns { "events": [ … ] }. Render from this rather than hardcoding, the catalog is a stable contract designed to grow.
2

Register an endpoint

url must be a valid https URL; events must be a non-empty array of known topics. The response includes the full whsec_… secret exactly once, store it now; later reads return only a masked hint.
3

Send a test delivery

Sends a signed ping through the real dispatch path, so a passing test proves your signature verification works, not just that your URL is reachable.
Managing endpoints is a dashboard/session action, not a sk_ secret-key call. The whsec_… secret is used only to verify deliveries on your side; it never authenticates a request to the platform.

Event catalog

Six topics emit today: The ping topic is delivered only by the Send test button; it isn’t subscribable and won’t arrive from real activity.
These public topics are intentionally decoupled from internal event names. Build against the topic strings above, not against internal delivery-event types you might see elsewhere.

Retries and health

Because failed deliveries retry and the same id can arrive more than once, your handler must be idempotent. Dedupe on id (or X-OnChain-Delivery) before taking any action with side effects. Return 200 fast, do slow work asynchronously so you don’t hit the 10-second timeout and trigger needless retries.
An endpoint that has flipped to failing (or that you’ve paused) delivers nothing until you set it back to active, which also resets its failure counter. Watch the endpoint’s status when webhooks go quiet.