Skip to main content

Webhooks

Use webhooks to send email-check, order/profile/cashier fraud, and MDM events to your server. Webhooks require Starter or higher.

Set up an endpoint​

  1. Open Dashboard → Webhooks and create a public HTTPS endpoint.
  2. Choose the exact event types you want.
  3. Copy the signing secret when it is shown. It cannot be retrieved later; rotate it if it is lost.
  4. Send a test event and confirm a successful delivery in history.

Management API calls use a portal bearer token, not an SDK/secret API key. See the Webhooks API reference for paths and the current event list.

Verify every delivery​

Read the request body as raw bytes before JSON parsing. Parse X-Simplr-Signature, then compute HMAC-SHA256 over <timestamp>.<raw-body> with your webhook secret. Compare the result to the v1 value using a timing-safe comparison.

import crypto from "node:crypto";

export function verifySimplrWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=", 2)));
  if (!parts.t || !parts.v1) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const actual = Buffer.from(parts.v1, "hex");
  const wanted = Buffer.from(expected, "hex");
  return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}

Also reject timestamps outside your replay window and deduplicate on X-Simplr-Delivery. Respond with 2xx quickly, queue the work locally, and make processing idempotent because retries can deliver the same event again.

Operate delivery​

The dashboard/API lets you inspect delivery attempts, pause or resume an endpoint, send a test delivery, rotate its secret, and delete it. A rotated secret invalidates the previous secret immediately, so coordinate rotation with the receiving service.