How signing works
Every delivery carries two headers:- Build the signed payload: the timestamp, a period, and the raw request body:
<timestamp>.<raw body>. - Compute an HMAC with SHA-256, using your endpoint’s signing secret as the key. The key is the full secret string, including its
whsec_prefix. - Hex-encode the result (64 lowercase characters) and prefix it with
v1=.
Verify a delivery
1
Read the raw body
Use the exact bytes you received. Parsing the JSON and serializing it again changes whitespace and key order, and the signature won’t match.
2
Check the timestamp
Reject the delivery if
X-Quotable-Timestamp is more than 300 seconds (5 minutes) away from your server’s clock. This stops someone from replaying a captured delivery later.3
Compute and compare
Compute the expected signature and compare it with every
v1= value in X-Quotable-Signature, using a constant-time comparison. Accept the delivery if any one matches.4
Deduplicate
After the signature checks out, skip the event if you’ve already processed its
id. Deliveries are at-least-once.401 or 400 when verification fails. Quotable treats that as a failed attempt and retries, which is what you want if your secret was briefly out of date.
Code
Get the raw body in your framework
Most frameworks parse JSON for you, which throws the raw bytes away. Read the raw body first, verify, then parse.- Next.js (App Router)
- Express
- Flask
- FastAPI
app/api/quotable-webhook/route.ts
request.json() before verifying: once the body is consumed as JSON, you can’t get the original bytes back.Test your implementation
Run your verifier against this known-good input. Disable the timestamp check for this test, since the timestamp is in the past.
You can reproduce the signature from a shell:
Secret rotation
When you select Rotate secret for an endpoint, Quotable shows a new secret once. For the next 24 hours, every delivery carries two signatures: one with the new secret and one with the previous secret. A verifier that accepts any matchingv1= value keeps working with either secret, so you can deploy the new one at any point in that window.
After 24 hours, only the new secret signs. Deliveries checked against the old secret then fail and are retried, so update your verifier before the window ends. See Manage endpoints.
Security checklist
Use a constant-time comparison
Use a constant-time comparison
Compare signatures with
timingSafeEqual (Node.js), hmac.compare_digest (Python) or hmac.Equal (Go). A plain === or == leaks timing information.Keep the timestamp check
Keep the timestamp check
Without it, a captured delivery can be replayed forever. Keep your server clock in sync with NTP so honest deliveries stay within 300 seconds.
Store the secret like a password
Store the secret like a password
Keep it in an environment variable or a secret manager, never in source control. It’s shown only when you create the endpoint or rotate the secret.
Next steps
Delivery and retries
What counts as success, and when Quotable tries again.
Slack alerts recipe
A complete receiver that verifies and forwards to Slack.