Why verify
Your endpoint is a public URL, so anyone can send aPOST 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.
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 formwhsec_ 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.How the signature is made
- StockInsights joins the event id, the timestamp and the raw request body with
dots:
{webhook-id}.{webhook-timestamp}.{body}. - It computes an HMAC-SHA256 of that text. The key is the base64-decoded part
of the secret after
whsec_. - It encodes the HMAC as base64 and sends it as
v1,<signature>in thewebhook-signatureheader.
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.
Verify with a library
The Standard Webhooks libraries do all the steps, including the timestamp check. They take the secret with itswhsec_ prefix.
Verify without a library
After the check
- Answer with a
2xxstatus 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.