When you receive webhook notifications from BotSubscription, you must verify their authenticity and integrity before processing any payload or database side effects. This ensures that the requests originate from our secure servers and have not been tampered with in transit.
When integrating webhooks to synchronize events with your own custom backend or database, verifying signatures is a critical requirement for protecting your system against spoofing and replay attacks.
When you create or inspect a webhook endpoint in your dashboard, you are issued a 64-character hexadecimal Signing Secret (e.g., 64_character_hex_string_here...).
Keep this secret secure. Do not commit it to version control or expose it on client-side code. Treat it like an API key.
Concatenate the timestamp t, a literal period ., and the exact raw HTTP request body bytes:
<timestamp_value>.<raw_http_request_body>
Warning
Use raw bytes: You must read the request body in its raw, unparsed form. Standard web application frameworks often parse JSON into objects automatically, which changes the whitespace, key order, or byte representation. Using parsed or re-serialized JSON will cause signature validation to fail.
Extract the Header: Parse the X-Webhook-Signature header to extract the values of t and v1.
Validate Time Drift: Check the timestamp t against your server's current time. Reject the request if the difference exceeds 5 minutes (300 seconds) to prevent replay attacks.
Compute the Local Signature: Using the secret and the raw payload string <t>.<raw_body>, compute the HMAC-SHA256 signature.
Perform a Safe Comparison: Compare your computed signature with the v1 value using a constant-time comparison helper. This prevents timing analysis attacks.
Use this purely client-side sandbox to verify your signature computation logic or to generate valid signatures for manual testing. None of your input data or secrets are sent to any server.
Your webhook endpoint's secret key. Stays entirely local in your browser.
Unix epoch timestamp in seconds representing when the signature was created.
Paste the full X-Webhook-Signature header value from the received request.
The exact raw HTTP request body string. Make sure there are no modified whitespaces.
Verification Result
Fill out the signing secret, signature header, and JSON payload above to run verification.
Signature Verified Successfully!
The computed HMAC signature matches the received signature perfectly. This request is verified, authentic, and untampered.
Signature Verification Failed
The computed signature does not match the signature provided in the header. Please verify your secret key, timestamp, and raw payload.
Timestamp Drift Alert (Replay Vulnerability)
The signature is cryptographically valid, but the timestamp differs by more than 5 minutes (300s) from current time. In production, your server should reject this request to prevent replay attacks.
Generated Signature Header
t=...,v1=...
Inject this exact value as the X-Webhook-Signature header in your test request.