Webhooks API

All routes live under /api/v1/webhooks. A request with an X-API-Key header is an API key request. Any other request must carry a dashboard session. See the API Overview. Every route is limited to the account that owns the webhook.

The account check differs for the two credentials. A dashboard session must hold a role on the account that is at least the role the route names. The role is viewer to read a webhook or its delivery history. The role is member to create, update or delete a webhook, and to call test or redeliver.

An API key has no role. RealmSSO checks the key against the one account it was made for, and then against its scopes. Reads need webhooks:read. Each write needs webhooks:write, including test and redeliver, because both send a request out. A key that holds only webhooks:read gets 403 on those two.

Events

A webhook's events array names the events it wants. A webhook receives a delivery when it is enabled and events holds the event name or the wildcard *. The wildcard means every event the server emits, including events added after you wrote the configuration. The wildcard is the whole matching language. There are no prefixes and no globs, so connection.* matches nothing.

Payload

The request body is the event object itself, serialized as JSON. There is no envelope. Do not rely on the key order.

{
  "connectionId": "clx9f0a2b0001abcd",
  "accountId": "clx8e1b3c0002efgh",
  "previousStatus": "active",
  "status": "error",
  "changedAt": "2026-09-02T19:18:21.000Z"
}

previousStatus and status are connection statuses (active, inactive, error, pending). changedAt is an ISO 8601 timestamp. RealmSSO sets it when it emits the event. The body is a snapshot of what was true when the event happened. A retry sends the same bytes. It does not read the connection again.

The test route below sends a different shape: { "event": "test", "timestamp": …, "data": { "message": … } }. Branch on the X-SSO-Plane-Event header, not on body fields.

Request headers and signature

Every attempt is an HTTP POST with these headers. This holds for the dispatcher and for the test route.

The canonical string has five fields joined by single newlines. These are the literal v1, the timestamp header, the delivery header and the event header. The last field is the raw request body, byte for byte. Compute HMAC-SHA256 over it with the secret exactly as issued, whsec_ prefix included. Hex-encode the result. Compare it in constant time with the v1= element of the signature header.

Reject a timestamp that is further from your clock than your tolerance. 300 seconds is the recommended default. Verify the bytes you received, not a re-serialization of the parsed JSON. A round trip through a JSON library can reorder keys or change number formats. The digest then differs, and it looks like an attack.

const { createHmac, timingSafeEqual } = require('crypto');

function verifyRealmSSOWebhook({ secret, rawBody, headers, toleranceSeconds = 300 }) {
  const timestamp = Number(headers['x-sso-plane-timestamp']);
  if (!Number.isInteger(timestamp)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;

  const presented = (headers['x-sso-plane-signature'] ?? '')
    .split(',')
    .map((part) => part.trim())
    .find((part) => part.startsWith('v1='))
    ?.slice(3);
  if (!presented) return false;

  const canonical = [
    'v1',
    String(timestamp),
    headers['x-sso-plane-delivery'],
    headers['x-sso-plane-event'],
    rawBody,
  ].join('\n');
  const expected = createHmac('sha256', secret).update(canonical, 'utf8').digest('hex');

  const a = Buffer.from(presented, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && timingSafeEqual(a, b);
}

When verification fails, return 400 and process nothing. Do not return 2xx. RealmSSO treats any non-2xx response as a failed attempt and retries it, so a rejected forgery costs you nothing. A 2xx on a bad signature tells the sender that the forgery worked. To check your verifier, use the test delivery below. RealmSSO signs it the same way as a real delivery.

The signing secret

RealmSSO generates the secret when you create the webhook. It is 32 random bytes as hex, behind a whsec_ prefix. The 201 response returns it as data.secret. RealmSSO discards a secret that you send in the create body. There is no rotation endpoint. To replace a secret, delete the webhook and create it again.

How a delivery is made

When an event matches a webhook, RealmSSO writes one delivery row for each matching webhook. The row starts in state pending. The dispatcher claims due rows in a pass every 5 seconds. It makes one attempt for each claimed row in a pass.

In one pass, the dispatcher claims at most one row for each webhook. A slow receiver holds up only its own attempt in that pass, for up to 10 seconds. The next pass starts only after the current pass ends. The row is the record, not the process, so a server restart does not lose a queued delivery. Measured on 2026-09-14: the dispatcher was running on production, with a pass every 5 seconds.

Create a webhook

Returns 201 with the webhook, including the generated secret. enabled defaults to true. The dashboard creates webhooks with events: ["*"].

List, get, update, delete

The list requires accountId, and answers 400 without it. It is one of the unpaginated lists: a bare { data: [...] }, newest first, with no meta. PATCH accepts any of url, events and enabled. RealmSSO checks a new url the same way as at create time. DELETE returns 204 and removes the webhook's delivery history with it.

Delivery history

The list is paginated (page and limit, capped at 100), newest first. Each row is the queue record, returned as stored. The dashboard shows the same history.

{
  "data": [
    {
      "id": "clx9f0a2b0001abcd",
      "webhookId": "clx7d2c4e0003ijkl",
      "eventType": "connection.status.changed",
      "payload": { "connectionId": "…", "accountId": "…", "previousStatus": "active", "status": "error", "changedAt": "…" },
      "state": "dead_letter",
      "attempt": 3,
      "statusCode": 503,
      "responseBody": null,
      "success": false,
      "nextRetryAt": null,
      "completedAt": "2026-09-02T19:19:01.000Z",
      "createdAt": "2026-09-02T19:18:21.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}

attempt counts the attempts made so far. statusCode is the last response status. It is 0 for a network error or a timed-out attempt, and null when RealmSSO dialled nothing. success and completedAt are kept for compatibility. state decides.

Redeliver

Resets a final row (delivered or dead_letter) to pending with attempt: 0, due now. The next pass sends it the normal way. The delivery id is the same, so your idempotency key still holds. The timestamp and signature are new. The dashboard can also redeliver a delivery.

Returns 202 with the reset row. The send has not happened yet, so read the result from the delivery history. Returns 404 in three cases. The webhook is disabled, the delivery belongs to another webhook, or the row is still pending. A pending row is due or in an attempt, and a reset would send it twice. Redelivery reaches back as far as retention. RealmSSO purges final rows after 90 days, and a purged row cannot be redelivered.

Send a test delivery

Synchronous. It sends a test event. The signing, the per-attempt deadline and the retry schedule are the same as for a real delivery. It waits for the delivery to finish, which can take about 45 seconds, and returns the result. The row it writes appears in the delivery history like any other.

{
  "data": { "deliveryId": "clx9f0a2b0001abcd", "statusCode": 200, "success": true, "attempts": 1 }
}