SapaganDocs sapagan.com

Guides

Webhooks

Call your own URL from a journey, and verify each request with X-Sapagan-Signature.

A webhook is a journey step that sends a signed POST to your URL. Use it to sync a CRM, start a workflow or tell another system that a person reached a step.

Add a "Send webhook" step in the journey designer and give it a URL, a JSON body and a secret. The step is for workspace journeys. A store's flow cannot use it.

The request#

Sapagan sends a POST with a JSON body:

{
  "delivery_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "profile": { "id": "user-42" },
  "event": { "name": "order_placed" },
  "journey": { "id": "...", "step": "...", "run": "..." },
  "data": { "orderId": "1042" }
}

data is the body you wrote in the step. Each string in it is rendered with Liquid, with the roots customer, event and delivery. profile carries only the external id, so personal data leaves only through what you write in data.

Headers on every attempt:

HeaderValue
X-Sapagan-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>
X-Sapagan-TimestampThe same t.
X-Sapagan-DeliveryThe delivery id. The same on every retry.
X-Sapagan-AttemptThe attempt number.

Verify the signature#

The signature is HMAC-SHA256(secret, t + "." + body), as hex, where body is the raw request body.

  1. Read the raw body, before any JSON parsing.
  2. Read t and v1 from X-Sapagan-Signature. A header may carry two v1 parts while a secret is being rotated. Accept any that matches.
  3. Reject when t is more than 5 minutes from your clock. The signature covers t, so a replay cannot move it forward.
  4. Recompute the HMAC with the secret's exact text as the key and compare in constant time.
  5. Treat X-Sapagan-Delivery as an idempotency key. Delivery is at least once.
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.SAPAGAN_WEBHOOK_SECRET;

app.post("/hooks/sapagan", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Sapagan-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401);

  const expected = createHmac("sha256", SECRET).update(`${t}.`).update(req.body).digest();
  const candidates = header.split(",").filter((p) => p.startsWith("v1=")).map((p) => Buffer.from(p.slice(3), "hex"));
  const ok = candidates.some((c) => c.length === expected.length && timingSafeEqual(c, expected));
  if (!ok) return res.sendStatus(401);

  const delivery = req.get("X-Sapagan-Delivery");
  // Skip if you already handled this delivery id, then:
  const payload = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(200);
});

Retries#

AnswerWhat Sapagan does
2xxDone. The body is never read.
5xx, 408, 429, a timeout, a connection or TLS failureRetry.
410Fail at once.
Any other 4xx and any 3xxFail, no retry.

There are 8 attempts, waiting 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 5 hours and 10 hours between them: about 18 hours in all. A Retry-After is honoured up to one hour. Every attempt is signed again with a fresh t. A receiver that answers 401 for a bad signature is not retried.

Rules for the URL#

  • https only, on port 443 or 1024 to 65535. No redirects.
  • Every address the name resolves to must be public. Private, loopback, link-local and cloud metadata ranges are refused (host_not_allowed).
  • The request body is at most 64 KiB and the whole exchange is limited to 10 seconds. Answer fast and work later.
  • Worker egress must reach your host over https.

Secrets#

The step names a secret from the vault, with a name that starts webhook_. The value is read only when sending, and never appears in the journey, an API response or the console. Today Sapagan adds the secret for you: there is no console upload yet. Ask for a webhook_* secret and choose it in the step.

A webhook is not a message to a person. Consent, unsubscribe, frequency caps and device rules do not apply. Kill switches do. A webhook in a marketing journey also waits for quiet hours to end, like a push.