Skip to main content
Anyone who learns your endpoint URL can send it requests. The signature proves a delivery came from Quotable and wasn’t changed on the way. Verify it on every request, before you parse or act on the body.

How signing works

Every delivery carries two headers:
The signature is computed like this:
  1. Build the signed payload: the timestamp, a period, and the raw request body: <timestamp>.<raw body>.
  2. 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.
  3. Hex-encode the result (64 lowercase characters) and prefix it with v1=.
During a secret rotation, the header carries two signatures separated by a comma, one per secret:

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.
Answer 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.
app/api/quotable-webhook/route.ts
Don’t call 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 matching v1= 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

Compare signatures with timingSafeEqual (Node.js), hmac.compare_digest (Python) or hmac.Equal (Go). A plain === or == leaks timing information.
Without it, a captured delivery can be replayed forever. Keep your server clock in sync with NTP so honest deliveries stay within 300 seconds.
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.
A valid signature proves the event came from Quotable. Before you act on ids in the payload, fetch the record from the API with your own key if the action matters.

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.
Last modified on November 18, 2026