Verify webhook signatures
Summary
Every webhook the platform sends to a Webhook URL destination is signed, so your receiving endpoint can confirm a request genuinely came from CyberHQ.ai rather than trusting the URL alone. This article covers how to check that signature.
Before you start
You'll need a Webhook URL destination. To add one, go to Integrations → Notifications, select Add destination under Notification destinations, and choose Webhook URL. The signing secret is shown once, in a panel at the top of Notification destinations, when you create the destination or select Rotate secret on its row: copy it immediately.
1. Read the two signature headers
Every delivery carries:
- X-CyberHQ-Timestamp: when the request was sent, as epoch seconds.
- X-CyberHQ-Signature: in the form sha256=<hex>.
2. Recompute the signature
The signature is an HMAC-SHA256 of the string <timestamp>.<body> (the timestamp header's value, a literal period, then the raw request body), keyed by your destination's signing secret. In pseudocode:
signed_string = timestamp + "." + raw_body
expected = hmac_sha256(secret, signed_string) # hex-encoded
Compare expected against the hex value after sha256= in the X-CyberHQ-Signature header. Use a constant-time comparison rather than a simple string equality check, to avoid leaking timing information about how much of the signature matched.
3. Reject stale requests
Check the timestamp is within an acceptance window you're comfortable with (a few minutes is typical) before trusting the payload: this is what stops a captured, genuine request from being replayed later. A valid signature on an old timestamp should still be rejected if it falls outside your window.
4. Know the delivery behavior
- Deliveries retry on a 5xx response or a network error: up to two retries, with a short backoff between attempts.
- A 4xx response is not retried: the platform treats it as a rejection, not a transient failure, so make sure your endpoint only returns a 4xx when the request genuinely shouldn't be retried.
- Redirects aren't followed, and only HTTPS destinations are supported.
Confirm it worked
Select Test on the destination's row under Notification destinations to send a test delivery, and confirm your endpoint recomputes a matching signature against the payload it received. If the test doesn't arrive, see An expected notification didn't arrive.
If it didn't work
- Signature never matches: the most common cause is signing the wrong string; confirm you're hashing <timestamp>.<body> exactly, using the raw request body before any JSON parsing or re-serialization, which can change whitespace and break the match.
- Signature matched once, then stopped: the destination's signing secret may have been rotated; it's shown only once, so update your verification code with the new value if you rotated it deliberately.
- Endpoint gets hit repeatedly for the same event: check whether your endpoint is returning a 5xx by mistake for a request it actually handled successfully; that triggers a retry your endpoint doesn't need.