Webhook signing
What is Webhook signing?
Webhook signing is the practice of cryptographically stamping each webhook delivery at send time so the receiving application can prove the payload really came from the platform. Orbit signs every delivery with HMAC-SHA256 keyed by your endpoint's signing secret and stamps the result in the X-Orbit-Signature header as t=<unix_ts>,v1=<hex>, so your receiver can recompute the digest before it trusts the event.
More detail
Signing is what moves the webhook from bearer URL to authenticated channel: the webhook signing secret is provisioned per endpoint (each endpoint carries its own whsec_ value shown once at creation), and none of the event envelope fields — the event id, type, timestamp or payload body — count as trustworthy until a recomputed signature matches. Rotating the secret starts a grace window in which Orbit signs with the new secret and still honours the previous one, so a receiver can carry both during a cutover.
Because the signature covers the exact raw delivery bytes, a signing-aware receiver verifies the request body verbatim — the whole payload participates — and rejects deliveries whose t= timestamp falls outside the five-minute replay window. The receiver-side verification recipe lives on the sibling webhook signature term, and the docs Webhook Security guide ships a worked sample test-receiver in seven languages — all tenant-owned controls: Orbit signs, your endpoint chooses what to accept.
Frequently asked
- Where do I find my webhook signing secret?
- At endpoint creation — the full whsec_ value is shown once, and later GET /api/v1/webhooks/{id} calls only return the masked preview. If the creation-time value was lost, rotate the secret on the endpoint and record the new value; keep the previous one on hand while the rotation grace window is open so in-flight deliveries still verify.
- Does signing replace endpoint authentication?
- It replaces it for the platform-to-you direction: instead of you handing Orbit a credential for your endpoint, Orbit proving its identity to you. Your endpoint should still be a hard-to-guess URL or sit behind network controls, but the signed digest over the raw bytes is the check that proves a delivery genuinely came from Orbit and wasn't replayed or tampered with.
- Is webhook signing the same as webhook signature verification?
- Two directions of one contract: signing is what Orbit does when stamping the delivery (HMAC-SHA256 over the timestamp and raw body, stamped as X-Orbit-Signature); signature verification is the receiver-side recompute-and-compare your code performs. The webhook signature term covers the verification side.
See also
Build it on Orbit
Voice, messaging, email, video, and AI agents on one platform and one pay-as-you-go bill. Start free — no credit card required.