Spec the signature check for your partners' webhooks

Vibe codingHard25 minStripe style

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_secrets table, 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?