Webhooks

Register

The lifecycle of a delivery

1. The event happens

   Step 01
   A suppression is registered, changed, or expires. The event gets an id that stays stable across every delivery attempt.

2. The payload gets signed

   Step 02
   The body is signed with your webhook key and the signature is placed in the X-MarketMute-Signature header.

3. Delivery to your endpoint

   Step 03
   An HTTP POST to the address you registered. Verify the signature before you read the contents.

4. You acknowledge

   200204
   One of these two responses closes out the delivery. Acknowledge only once you've actually taken responsibility for the event — not before.

5. Otherwise: another attempt

   Max 5 attempts
   Anything other than an acknowledgment counts as a failed attempt. We redeliver with exponential backoff, up to five attempts total.

Verify the signature

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verify(rawBody: Buffer, header: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const received = Buffer.from(header, "hex");
 
  // Different length => never valid, and timingSafeEqual throws.
  if (expected.length !== received.length) return false;
 
  return timingSafeEqual(expected, received);
}

Consume idempotently

// Acknowledge immediately if the event's already been processed.
if (await seen(event.id)) {
  return response(204);
}
 
await apply(event);
await remember(event.id);
return response(204);