Webhooks

1. In the dashboard, open Account → Webhooks and add your endpoint URL (must be HTTPS in live mode).
2. Choose which event types the endpoint should receive.
3. Copy the endpoint's signing secret and store it in your server environment (e.g. SALEONIX_WEBHOOK_SECRET). You can reveal it again or roll it from the dashboard at any time.

Test-mode payments send order.paid, order.payment_failed and invoice.paid exactly like live ones, so you can build and test your handler before going live. payout.* events fire for every payout, including Payout Now.

webhook.test is sent by the Send test event button in your dashboard. It is never produced by real store activity, so a handler that switches on the types above will ignore it safely.

Every delivery is a JSON POST with the same Stripe-style envelope. Retries always send the identical body:

{
  "id": "evt_...",
  "object": "event",
  "type": "checkout.session.completed",
  "livemode": false,
  "created": 1780000000,
  "data": {
    "object": {
      "id": "cs_test_aBcD...",
      "object": "checkout.session",
      "status": "complete",
      "payment_status": "paid"
      // … the full resource
    }
  }
}

Each request carries a Saleonix-Signature header:

Saleonix-Signature: t=1780000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

The signature is HMAC-SHA256(secret, `{t}.{rawBody}`). Because the timestamp is signed, captured requests can't be replayed outside the 5-minute tolerance window. Always verify against the raw request body — parsing and re-serializing JSON will break the signature.

const crypto = require("crypto");

const TOLERANCE_SECONDS = 5 * 60;

function verifyWebhookSignature(rawBody, header, secret) {
  let timestamp = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.split("=", 2).map((s) => (s ?? "").trim());
    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
    if (key === "v1" && /^[0-9a-f]{64}$/.test(value)) signatures.push(value);
  }
  if (timestamp == null || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return signatures.some((sig) => {
    const a = Buffer.from(sig, "hex");
    const b = Buffer.from(expected, "hex");
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

// Express example — note: you need the RAW body, not parsed JSON.
app.post("/webhooks/saleonix", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.headers["saleonix-signature"] || "";
  if (!verifyWebhookSignature(req.body.toString("utf8"), header, process.env.SALEONIX_WEBHOOK_SECRET)) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  switch (event.type) {
    case "checkout.session.completed":
      // ✅ fulfill the order for event.data.object
      break;
    case "subscription.past_due":
      // ⚠️ notify the customer
      break;
  }
  res.status(200).send("ok"); // acknowledge fast; do slow work async
});

A delivery succeeds on any 2xx. Anything else — including a timeout — is retried. You have 10 seconds to respond before we give up on an attempt.

Each delay carries ±15% jitter. After the 6th failed attempt the delivery is marked failed and stops. You can re-send it by hand from Recent events in your dashboard. An endpoint that accumulates 20 consecutive failed deliveries is automatically disabled — re-enable it there once your handler is fixed.

Events that happen while an endpoint is disabled are not lost: they are recorded as failed deliveries. After re-enabling, choose Resend failed deliveries on the endpoint to queue every failed delivery from the last 7 days again.

Alongside the signature, every request carries:

• Return 200 quickly. Acknowledge the delivery, then do slow work (emails, provisioning) asynchronously. Non-2xx responses are retried.
• Be idempotent. Store processed event ids and skip duplicates — retries and redeliveries can send the same event more than once.
• Don't rely on delivery order. Retries and resends can deliver events out of sequence — for example order.refunded before the order.paid it follows. Compare the envelope's created timestamp, or fetch the current state from the API, instead of assuming the latest delivery is the latest state.
• Don't trust the payload alone for money decisions. For fulfillment you can additionally retrieve the session with your secret key as a second check.
• Check livemode so test events never trigger production fulfillment.