Webhooks - Kourio

Each delivery event becomes a POST to your endpoint: accepted, delivered, deferred, bounced, complained.

Verify the signature

Every delivery is signed in kourio-signature. Verify it before trusting the body — without that, anyone who discovers your URL can forge an event and, for example, mark an order as delivered.

import { verifyWebhookSignature } from '@kourio/sdk';

app.post('/webhooks/kourio', async (req, res) => {
  const valid = verifyWebhookSignature({
    payload: req.rawBody,          // the raw body, before parsing
    signature: req.headers['kourio-signature'],
    secret: process.env.KOURIO_WEBHOOK_SECRET!,
  });
  if (!valid) return res.status(401).end();

  res.status(200).end();          // answer fast; process afterwards
});

Use the raw body. If you verify the signature over an already-parsed and re-serialized object, key order or one extra space changes the bytes and the check fails for a reason that has nothing to do with security.

Answer fast

Return 200 as soon as you receive it and process afterwards. A slow endpoint becomes a retry, and a retry becomes a duplicate event in your system. Treat events as at least once: the same event can arrive twice. The event id is what lets you ignore the second one.

When an event does not arrive

GET /v1/webhooks/{id}/deliveries brings each attempt with the status code and the body your server returned. It is what answers “why didn’t it arrive” without depending on your logs.