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:
| Header | Value |
|---|---|
X-Sapagan-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> |
X-Sapagan-Timestamp | The same t. |
X-Sapagan-Delivery | The delivery id. The same on every retry. |
X-Sapagan-Attempt | The attempt number. |
Verify the signature#
The signature is HMAC-SHA256(secret, t + "." + body), as hex, where body is the raw request body.
- Read the raw body, before any JSON parsing.
- Read
tandv1fromX-Sapagan-Signature. A header may carry twov1parts while a secret is being rotated. Accept any that matches. - Reject when
tis more than 5 minutes from your clock. The signature coverst, so a replay cannot move it forward. - Recompute the HMAC with the secret's exact text as the key and compare in constant time.
- Treat
X-Sapagan-Deliveryas 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);
});import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["SAPAGAN_WEBHOOK_SECRET"].encode()
@app.post("/hooks/sapagan")
def sapagan_hook():
header = request.headers.get("X-Sapagan-Signature", "")
items = [p.split("=", 1) for p in header.split(",") if "=" in p]
t = next((v for k, v in items if k == "t"), None)
if t is None or abs(time.time() - int(t)) > 300:
abort(401)
body = request.get_data() # the raw bytes
expected = hmac.new(SECRET, t.encode() + b"." + body, hashlib.sha256).hexdigest()
if not any(hmac.compare_digest(v, expected) for k, v in items if k == "v1"):
abort(401)
delivery_id = request.headers.get("X-Sapagan-Delivery")
# Skip if you already handled this delivery id, then:
payload = request.get_json()
return "", 200Retries#
| Answer | What Sapagan does |
|---|---|
2xx | Done. The body is never read. |
5xx, 408, 429, a timeout, a connection or TLS failure | Retry. |
410 | Fail at once. |
Any other 4xx and any 3xx | Fail, 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#
httpsonly, 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.
Quiet hours and consent#
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.