Events & webhooks

Set up your endpoint and check that it works

1. 1
   Add an endpoint

   Use Add endpoint in Developers → Webhooks, or POST /v1/webhook_endpoints. Subscribe it to the events you act on, such as payment_intent.succeeded and payment_intent.failed.

2. 2
   Store the signing secret

   It is shown once, when you add the endpoint or rotate its secret. Keep it in your server's secret store.

3. 3
   Check that it works

   Create a payment with +263 77 000 0001, as in quickstart step 3, then open the endpoint's Deliveries to see the delivery and the HTTP status your server answered.

4. 4
   Developing locally?

   Expose your endpoint over HTTPS with a tunnel, or read GET /v1/events instead of waiting for deliveries.

Verify the signature before you trust a delivery

Each event arrives as a POST with a JSON body and the headers below. The signature covers the delivery ID and the exact bytes of the body, so check it before you parse or store anything.

1. 1
   Rebuild the signed payload

   Join the t value, the Perion-Delivery-Id header, and the raw request body with periods: {t}.{delivery ID}.{raw body}.

2. 2
   Compare it with every v1 entry

   Compute an HMAC-SHA-256 of that payload, keyed with the endpoint's whole signing secret, including its whsec_ prefix. Accept the delivery if the hex digest matches any v1 entry, using a constant-time comparison.

3. 3
   Reject old signatures

   Reject a t more than five minutes (300 seconds) from your server's clock. Every delivery attempt is signed when it is sent, so a retry carries a new t.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact request bytes (a Buffer), read before any JSON parsing.
// secrets: your current signing secret, plus the previous one during a rotation.
export function verifyPerionSignature(rawBody, headers, secrets, toleranceSeconds = 300) {
  const entries = String(headers["perion-signature"] ?? "").split(",").map((entry) => entry.trim().split("="));
  const timestamp = Number(entries.find(([key]) => key === "t")?.[1]);
  const signatures = entries.filter(([key]) => key === "v1").map(([, value]) => Buffer.from(value ?? "", "hex"));
  const deliveryId = String(headers["perion-delivery-id"] ?? "");
  if (!Number.isSafeInteger(timestamp) || signatures.length === 0 || !deliveryId) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.${deliveryId}.`), rawBody]);
  return secrets.some((secret) => {
    const expected = createHmac("sha256", secret).update(signedPayload).digest();
    return signatures.some((candidate) => candidate.length === expected.length && timingSafeEqual(candidate, expected));
  });
}

Respond with a 2xx status within 10 seconds, once the event is stored. Any other status, a redirect, or a timeout counts as a failed attempt: the delivery is retried with growing delays, up to six hours apart, for 72 hours. After that the delivery shows Stopped retrying; replay it from the endpoint's deliveries, or read it from GET /v1/events.

Event types

Subscribe an endpoint to exact event types, or to every type for one object with a wildcard such as payment_intent.*. These are all 83 event types an endpoint can subscribe to.