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 oftimestamp.rawBody, keyed with the whsec_… secret shown once when you create the endpoint.
The delivery
Each event is an HTTPPOST to your URL with a JSON envelope:
Headers
The signature, exactly
tis the emit time in Unix seconds.v1isHMAC_SHA256(secret, "<t>.<rawBody>")as a lowercase hex string.secretis the fullwhsec_…string, used verbatim as the HMAC key (keep thewhsec_prefix).- The signed material is the literal
t, a period, then the raw body bytes.
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
{ "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
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
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.
