Moving from legacy to Svix

Register on Svix while legacy deliveries continue, accept both signatures, deduplicate, then retire the legacy registration.

Once Svix is enabled for your account, your legacy endpoints keep working. Nothing is switched over for you: you register endpoints on Svix, and for as long as the legacy registration also exists, every event is delivered twice - once with the x-fsk-wh-chksm checksum and once with the svix-* headers. This is expected, not a fault, and it lets you verify Svix handling against live traffic before anything is removed.

Svix webhooks are invite only. If Svix is not enabled for your account yet, there is nothing to move to - see Requesting access.

Step by step

Register your endpoint in the partner portal

Add the URL and subscribe it to the event types you handle. See Configuring endpoints.

Verify Svix signatures alongside the legacy checksum

Make your handler accept either signature scheme, keyed on which headers are present. See Handling both below.

Deduplicate on event ID

You will receive every event twice while both registrations exist. See Deduplicate on event.id.

Ask support to retire the legacy registration

Once you have observed Svix deliveries arriving and verifying correctly, contact support@doura.ca to remove the legacy configuration. After that, you can delete the legacy verification branch.

Handling both

While your endpoint is registered on both delivery methods, branch on which headers are present:

app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  let ok;
  if (req.header("svix-signature")) {
    ok = verifySvix(req);          // see Verifying signatures
  } else if (req.header("x-fsk-wh-chksm")) {
    ok = verifyLegacy(req.body, req.header("x-fsk-wh-chksm"));   // see Verifying the checksum
  } else {
    ok = false;                    // unsigned: reject
  }
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  if (alreadyProcessed(event.event.id)) return res.sendStatus(202);

  res.sendStatus(202);
  enqueue(event);
});

verifySvix is the check from Verifying signatures; verifyLegacy is the check from Verifying the checksum. A request with neither set of headers is unsigned and must be rejected. Once support confirms the legacy registration is removed, delete the legacy branch.

Use the same URL for both registrations only if you want to. Registering a new URL on Svix and leaving the legacy URL untouched also works, and keeps the two handlers apart. Deduplicate on event.id either way, because the same event still reaches both.

What does not change

The event payload and the event catalog are identical on both delivery methods.
event.id is the same value on both for the same event.
Your endpoint requirements - HTTPS, prompt 2xx, idempotency - are the same.