Verifying Webhook Signatures
To protect your application against spoofing and tampering, Onbo signs every outgoing webhook request using HMAC-SHA256.
Before processing an incoming webhook payload, your listener should verify that the request originated from Onbo and that its contents were not altered in transit.
The X-IdMission-Signature Header
Every webhook request sent by Onbo carries the X-IdMission-Signature header:
X-IdMission-Signature: t=1756500000,kid=whsec_a1b2c3d4,v1=9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8eThe header value contains key-value pairs separated by commas:
| Key | Description | Example |
|---|---|---|
t | Unix epoch timestamp (in seconds) when the signature was created. | 1756500000 |
kid | Key identifier / fingerprint (whsec_<8-char-hex>) of the signing secret. | whsec_a1b2c3d4 |
v1 | Lowercase hexadecimal HMAC-SHA256 signature calculated over the payload. | 9f8e7d6c5b4a... |
How Signature Verification Works
To verify a signature, your listener performs four steps:
1. Extract Header Components
Parse the X-IdMission-Signature header to extract the values for t (timestamp), kid (key identifier), and v1 (signature).
2. Verify Timestamp Freshness (Prevent Replay Attacks)
Compare the timestamp t with your server’s current time. If the difference is greater than 300 seconds (5 minutes), reject the request to prevent replay attacks.
| t_{\text{current}} - t_{\text{header}} | > 300 \implies \text{Reject Request}
3. Compute Expected HMAC Signature
Compute the HMAC-SHA256 digest using your organization’s secret key (as raw UTF-8 bytes).
The signature input is formed by concatenating the timestamp t, a literal dot (.), and the exact raw request body bytes:
signature_input = timestamp + "." + raw_request_body_bytes
expected_signature = hex_encode( HMAC_SHA256( secret, signature_input ) )[!CAUTION] CRITICAL INTEGRATION REQUIREMENT: You MUST compute the HMAC signature over the raw, unparsed request body bytes. Parsing the JSON body into an object and re-stringifying it changes key ordering, whitespace, and formatting, which will cause signature verification to fail.
4. Perform Constant-Time Comparison
Compare the computed expected_signature hex string with the extracted v1 value using a constant-time string comparison function to prevent timing attacks.