Verify a Webhook signature and prevent duplicates
Every request from your subscription is signed with HMAC-SHA256 using the subscription’s secret. Recompute the signature on the raw body, compare it in constant time, reject anything older than 5 minutes, and ignore repeated deliveries.
Steps
1
Read the
X-Corteksa-Signature header, in the format t=<unix seconds>,v1=<hex>.2
Reject the request if
t is more than 5 minutes away from your clock.3
Compute
HMAC-SHA256(signing_secret, t + "." + rawBody) as hex, on the raw body exactly as it arrived.4
Compare the result with
v1 using a constant-time comparison. If they differ, reject the request.5
Store
X-Corteksa-Delivery for every delivery you’ve processed, and ignore repeats while replying 2xx.6
Parse the JSON only after verifying.
How it works
Don’t re-serialize the body before verifying. Any change in spacing or order breaks the signature.
A delivery is retried on any reply that isn’t 2xx, or on a timeout, so the same event may reach you more than once.
If something goes wrong
What you see
Why
What to do
The signature never matches
You compute it on a re-serialized body, or with the wrong secret.
Use the raw body and the right secret.
The same event arrives twice
A retry after a slow reply.
Prevent duplicates with
X-Corteksa-Delivery.Good to know
The suggested time window is 5 minutes.
The secret shows once, when the subscription is created.
Did this guide solve it?
If not, we’ll ask what was missing.