Webhooks

Register a webhook

curl -X POST https://api.sendoracloud.com/api/v1/orgs/$ORG_ID/webhooks/endpoints \
  -H "x-api-key: sk_prod_..." \
  -d '{
    "url": "https://your-app.com/hooks/sendora",
    "projectId": "'"$PROJECT_ID"'",
    "events": [
      "auth.user_upgraded", "auth.device_takeover", "auth.user_merged",
      "auth.deletion_scheduled", "auth.deletion_cancelled",
      "push.delivered", "push.token_invalidated"
    ],
    "isActive": true
  }'

$ORG_ID is your Org ID (Dashboard → Settings → General). Requires an API key with the webhooks:write scope, or an Admin dashboard session. Returns the endpoint id + a one-time secret (32-byte hex, used to verify HMAC signatures) — save it now; read paths redact it to a secretConfigured boolean. If you lose it, POST .../endpoints/{id}/rotate-secret issues a fresh one (also returned exactly once) — you do not need to delete and re-register the endpoint.

projectId is required, and it decides what the endpoint receives. An endpoint is scoped to exactly one project: it gets that project's events and no other project's. If you run several apps in one workspace, register one endpoint per project rather than one endpoint for the workspace — a single URL receiving every project's end-user payloads is the shape this field exists to prevent. Every delivery also carries the resolved project at the top level as projectId, so a receiver can assert it matches the one it expects.

Signature verification

Each delivery carries one X-Sendora-Signature header in the format t=<unix_seconds>,v1=<hex> (Stripe-style). v1 is the HMAC-SHA256 hex digest of the string `${t}.${rawBody}` keyed by your endpoint secret. Verify against the exact raw body bytes — re-serializing the JSON changes key ordering and breaks the check. There is no separate X-Sendora-Timestamp header, and Sendora does not enforce a replay window; the t= value is provided so you can enforce your own.

import crypto from "node:crypto";

// rawBody = the exact request body string (do NOT JSON.parse then re-stringify)
function verify(rawBody: string, sigHeader: string, secret: string, toleranceSec = 300): boolean {
  const parts = Object.fromEntries(sigHeader.split(",").map((p) => p.split("=")));
  const { t, v1 } = parts;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false; // your policy — not enforced by Sendora
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Every delivery also sends X-Sendora-Event (the event type), X-Sendora-Delivery (the envelope id — your idempotency / dedup key, stable across retries), and X-Sendora-Attempt (1-based attempt counter).

What actually reaches your endpoint

Sendora webhooks come in two kinds. Getting this distinction right saves you from subscribing to events that never arrive.

1. Sendora system events (server-emitted)

A fixed set the platform emits server-side, with stable type strings and payload shapes. These are the only events Sendora originates for you — the table below is the complete list, 10 of them.

⚠ The table below is generated from the same registry the backend dispatches from, and a test fails the build if a payload here disagrees with the object we actually send. It used to be hand-written beside the code, and drifted — an integrator built against a description that omitted a field that was present, and another that promised one that was not. Build against this table.

⚠⚠ It also used to list more events than it should. This section rendered every auth.* shape in the registry, eight of which Sendora does not emit — they are passthrough shapes (kind 2 below) that only ever arrive if you post them yourself. Under a heading saying “the only events Sendora originates”, that read as a promise of delivery, and an integrator built two handlers for messages that could not arrive. It is now filtered on the same dispatchedBySendora flag the API serves, so the page and the dispatcher cannot disagree.

A key marked ? is conditional — present on one code path only. Branch on its presence; never expect it.

Being on this list is not a promise of traffic. auth.credential_revoked needs a real Apple consent-revocation before it ever fires for you. The list answers “can this arrive at all”; only your delivery log answers “has it arrived”.

You do not have to take this page's word for any of it. GET /orgs/:orgId/webhooks/event-types serves the whole catalogue as JSON with a dispatchedBySendora boolean per entry, from the same registry that generates this table — and since s58.342 a subscription to a name that is neither catalogued nor one of your own already-ingested event types is refused with a 422 rather than accepted with a 201.

2. Your own events (passthrough relay)

Every event you send to the Events API (POST /events or /events/batch) is relayed to any endpoint subscribed to that type (or *), with the type and properties exactly as you sent them — Sendora does not define or validate their shape. This is how you get order.shipped, level.completed, or any product event onto a webhook: emit it, subscribe to it, relay it.

There is no fixed server catalog of module webhook events. In particular, module analytics events — push.*, email.*, sms.*, geofence.*, and automation events — are written to your analytics event stream server-side and are not delivered to webhook endpoints. Query them via Analytics, or re-emit the ones you need through the Events API to relay them onward.

Naming caveat: passthrough matches on the exact type string, so an event you emit named auth.user_upgraded would be relayed indistinguishably from the real system event. Namespace your own events (e.g. app.*) to avoid colliding with the reserved auth.* / auth_service.* system names.

Payload envelope

{
  "id": "b3f1c2a4-5d6e-4f7a-8b9c-0d1e2f3a4b5c",   // plain UUID v4 — dedup key, same id on every retry
  "type": "auth.device_takeover",
  "orgId": "<ORG_UUID>",
  "projectId": "<PROJECT_UUID | null>",             // top-level, on EVERY event. null = org-wide scope
  "occurredAt": "2026-07-17T12:00:00.000Z",         // ISO-8601 UTC, set at dispatch time
  "properties": {                                    // type-specific — see per-event shapes below
    "anonUserId": "<UUID>",
    "identifiedUserId": "<UUID>",
    "projectId": "<PROJECT_UUID | null>"             // identity events also repeat it here
  },
  "context": { "source": "auth-service" }            // type-specific metadata, often {}
}

The envelope is identical for every event type: id, type, orgId, projectId, occurredAt, properties, and context.

⚠ This paragraph used to say there was no top-level projectId and to route you into properties for it. That has been wrong since the field was added: the dispatcher puts projectId at the top level of every envelope, and it is a pinned contract with a test that fails if it is dropped. Identity events additionally repeat it inside properties, which is what the old text was describing. Read the top-level one — it is the scope the delivery was actually resolved against.

null means org-wide scope. To map a projectId UUID to one of your apps, find it in the dashboard under Settings → Projects (each project row has a copy button), or list them via GET /orgs/:orgId/projects.

Use id as your idempotency key (also delivered as the X-Sendora-Delivery header). Sendora retries on 5xx / timeout / network errors, but id is stable across every attempt.

id format: a plain RFC-4122 UUID v4 — not prefixed and not time-sortable. Order events by occurredAt if you need chronology, and dedupe on id.

context carries optional per-event metadata (e.g. { "source": "auth-service" } on device-takeovers) and is {} for most events. Both properties and context are additive — treat unknown keys as forward-compatible, never reject on them.

System event payloads

The five server-emitted events, with their exact properties. Passthrough events carry whatever properties you sent to the Events API — Sendora relays them unchanged.

// auth.user_upgraded  — anon → real, sub preserved
{ "userId": "<uuid>", "email": "a@b.com", "isAnonymous": false,
  "projectId": "<uuid | null>" }

// auth.user_merged  — explicit merge(), anon sub remapped to target
{ "mergedUserId": "<uuid>", "deletedAnonymousId": "<uuid>",
  "eventsReassigned": 12, "profilesReassigned": 1, "pushTokensReassigned": 1,
  "projectId": "<uuid | null>" }

// auth.device_takeover  — sign-in / collision retires the anon sub
// context: { "source": "auth-service" }
{ "anonUserId": "<uuid>", "identifiedUserId": "<uuid>",
  "projectId": "<uuid | null>" }

// auth.user_deleted  — account permanently purged
{ "userId": "<uuid>", "email": "a@b.com", "projectId": "<uuid | null>" }

// auth_service.signing_key_rotated  — refresh your cached JWKS
// context: { "source": "auth-service" }
{ "newKid": "...", "previousKid": "...", "jwksUrl": "https://...",
  "overlapWindowMs": 86400000,
  "previousKeyExpiresAt": "2026-07-18T00:00:00.000Z" }

For identity semantics (which id is stable, when to re-key your own tables), see Identity in your backend and Device-takeover on signIn.

Retry policy

Your receiver must respond 2xx within 5 seconds. Anything else — non-2xx, timeout, or network error — triggers a retry.

• Schedule — up to 5 attempts total (1 initial + 4 retries) with backoff 2s → 8s → 30s → 90s (~2 minutes end to end). After the last attempt the delivery is marked permanently failed.
• No-retry codes — any 4xx except 408 and 429 is permanent (fix the receiver, then replay). 5xx, 408, 429, timeouts, and network errors are retried.
• Replay — Dashboard → Webhooks → Deliveries → Replay, or POST /orgs/:orgId/webhooks/logs/:logId/replay. Replay fires exactly one fresh attempt, not the full 5-attempt chain.
• No durable outbox — deliveries dispatch in-process (fire-and-forget). Ordering is not guaranteed, and a backend restart mid-retry can drop an in-flight delivery — reconcile critical state rather than relying on at-least-once alone.
• ⚠ occurredAt is stamped when we build the envelope, not when the underlying thing happened. For most events those are the same moment. They are not the same when an upstream provider redelivers a notification we already processed: we generate a fresh envelope, so the redelivery carries a newer occurredAt than events that legitimately came after it. Ordering on occurredAt alone will therefore re-apply a stale state change.
• For the identity-linkage events, order on stateVersion. auth.credential_revoked and auth.identity_reactivated describe opposite transitions of one linkage and both carry a per-linkage counter that only ever increments. Discard anything whose stateVersion is not greater than the state you already hold — >, never >=, since an equal version is the same state.

SSRF protection

Every delivery URL is validated before each attempt (and on manual replay), not just at registration. Blocked: RFC1918 (10/8, 172.16/12, 192.168/16), loopback (127/8), link-local (169.254/16 — which covers cloud-metadata 169.254.169.254), 0.0.0.0/8, CGN (100.64/10), and the IPv6 equivalents (::1, fc00::/7, fe80::/10, IPv4-mapped). Hostnames are DNS-resolved and the resolved address re-checked against the same list, failing closed on a resolution error. Use https:// + a publicly resolvable host.

More

• /docs/api — retry policy table.
• /docs/automation — webhook step config (workflow-driven webhooks; same retry + SSRF posture).
• /docs/push — Expo webhook bridge (concrete Node + Express + expo-server-sdk handler).