POLLING — you repeatedly ask "anything new?"          WEBHOOKS — they tell you when it happens
   every 30s:  GET /charges?since=...                     once, on the event:
      → mostly "nothing changed" (wasted calls)              provider → POST https://you/webhooks/stripe
      → up to 30s stale                                      → instant, no wasted requests
      → burns rate limit & CPU on both sides                → provider retries if you're down

import express from 'express'
import crypto from 'node:crypto'

const app = express()

// CRITICAL: capture the RAW body — signatures are computed over raw bytes,
// and JSON.parse + re-stringify changes them. Use the raw parser for this route:
app.post('/webhooks/provider', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature']
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)                                  // req.body is a raw Buffer here
    .digest('hex')

  // Constant-time compare to prevent timing attacks:
  const ok =
    signature &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!ok) return res.status(401).send('invalid signature')   // reject forgeries

  const event = JSON.parse(req.body.toString())        // safe to parse now
  handleEvent(event)
  res.sendStatus(200)
})

app.post('/webhooks/provider', express.raw({ type: 'application/json' }), async (req, res) => {
  verifySignature(req)                  // 1. verify (throws/401 on failure)
  const event = JSON.parse(req.body.toString())

  await queue.add('process-webhook', event)   // 2. ENQUEUE the work — don't do it inline

  res.sendStatus(200)                   // 3. ACK immediately (well under the provider's timeout)
})
// A separate worker consumes the queue and does the slow work (DB writes, emails, API calls).

// Providers guarantee AT-LEAST-once delivery → the same event WILL arrive twice.
// Dedupe on the provider's unique event id so processing is idempotent:
async function handleEvent(event) {
  const seen = await db.processedEvents.exists(event.id)
  if (seen) return                              // already handled — ignore the duplicate

  await db.transaction(async (tx) => {
    await applyEvent(event, tx)                 // do the real work
    await tx.processedEvents.insert({ id: event.id })   // mark done in the SAME tx
  })
}