Spec the signature check for your partners' webhooks
Your task
Your marketplace receives webhooks from 40 partner systems at POST /webhooks/:partnerId. Each partner signs requests Stripe style, with a header like X-Partner-Signature: t=1760000000,v1=5257a8.... There is no SDK for this, so a coding agent will write the check in TypeScript on Node. Payouts start from these events, so a forged or replayed one moves real money.
Write the spec you would hand the agent.
What you know:
- the signature is HMAC-SHA256 keyed with the partner's secret, over the timestamp, a period and the raw body, sent as lowercase hex in
v1 - secrets live in a
partner_secretstable, and during a rotation a partner has 2 active secrets for up to 24 hours - the Express app already applies
express.json()to every route - every event body carries a unique
event_id
Then, in a few sentences: what does "verify the webhook signature" leave out?