Skip to main content

Why verify

Your endpoint is a public URL, so anyone can send a POST to it. StockInsights signs every v2 request with a secret that only you and StockInsights know. When the signature is correct, the request came from StockInsights and its body was not changed on the way.
Verify the signature before you use the payload.
v2 uses the Standard Webhooks signature scheme. Thus you can use a Standard Webhooks library, or write the check yourself in a few lines.

Request headers

The signing secret

The v2 signing secret has the form whsec_ followed by base64, for example whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw. The part after whsec_ is the key, base64-encoded.
The v2 secret is the same key as your v1 secret, in another format. The v1 secret is hex. To get the v2 secret from it, decode the hex to bytes, encode the bytes as base64, and put whsec_ in front.
When you rotate the secret, the previous secret stops working at once. Deploy the new secret to your endpoint just before or just after you rotate.

How the signature is made

  1. StockInsights joins the event id, the timestamp and the raw request body with dots: {webhook-id}.{webhook-timestamp}.{body}.
  2. It computes an HMAC-SHA256 of that text. The key is the base64-decoded part of the secret after whsec_.
  3. It encodes the HMAC as base64 and sends it as v1,<signature> in the webhook-signature header.
The webhook-signature header can hold more than one signature, separated by spaces, for example during a key rotation. The request is valid when one of them matches.
Compute the HMAC over the raw request body, exactly as you received it. Do not parse the JSON and serialize it again: the bytes change, and the signature does not match.

Verify with a library

The Standard Webhooks libraries do all the steps, including the timestamp check. They take the secret with its whsec_ prefix.

Verify without a library

After the check

  • Answer with a 2xx status as soon as the signature is correct. Do slow work after you answer. See Delivery & retries.
  • De-duplicate on webhook-id. The same event can arrive more than once.
  • Refuse a request with an old webhook-timestamp. The libraries refuse a timestamp that is more than 5 minutes from your clock.