Skip to main content
Every webhook delivery is signed with HMAC-SHA256 using the secret you received when you created the endpoint. Always verify the signature before processing the payload. Without verification, anyone who knows your URL can impersonate Ontora.

How signing works

Ontora computes:
…and sends it in the X-Ontora-Signature header, prefixed with sha256=:
The body is JSON serialized with no whitespace between separators (, and :). Verify against the raw bytes of the request body — re-serializing the parsed JSON will produce a different hash and fail verification.

Verification examples

Checklist

  • ✅ Use a constant-time comparison (hmac.compare_digest, crypto.timingSafeEqual, hmac.Equal). Don’t compare with ==.
  • ✅ Verify against the raw request body, not a re-serialized parse.
  • ✅ Return 200 quickly and process asynchronously if your handler is slow.
  • ✅ Be idempotent — retries can deliver the same event twice. Use X-Ontora-Delivery-Id as a dedupe key.
  • ✅ Allow some clock skew when checking the timestamp in the payload.

Rotating the secret

To rotate, delete the old endpoint and register a new one with the same URL and events. There is currently no in-place rotation — this avoids the dual-secret window and keeps verification simple.