Webhooks 101 for developers

Webhooks are how a payment provider tells your server that something happened — a payment succeeded, a refund processed. If you're integrating payments, you'll live and die by them. Here's the essentials.

Webhook vs polling

Instead of your server constantly asking "is it paid yet?" (polling), the provider POSTs to your URL the moment something changes. It's faster, cheaper, and reliable.

The golden rule

Never trust a webhook you haven't verified. Anyone can POST to your URL. Every legitimate webhook is signed — an HMAC of the raw request body using your signing secret. Recompute it and compare.

const expected = crypto
  .createHmac('sha512', process.env.WEBHOOK_SECRET)
  .update(rawBody)         // the RAW bytes, not the parsed object
  .digest('hex')
if (expected !== req.header('x-twelveai-signature')) return res.status(401).end()

Respond fast

Acknowledge with a 2xx within a few seconds, then do your heavy work asynchronously. If you're slow, the provider assumes failure and retries.

Retries and idempotency

Providers retry failed deliveries — which means you'll sometimes get the same event twice. Make your handler idempotent: dedupe on the event id so a duplicate doesn't double-fulfil an order.

Use verify as a backstop

If a webhook is ever missed (your server was down), call the verify endpoint to re-check. Belt and braces.

Get signatures, fast acknowledgement, and idempotency right, and your payments integration will be rock solid.