Webhooks and the feed through the API¶

This page is for whoever has their own program follow what changes in OS. It shows how to read the feed, register a webhook, check a delivery and what to do when something goes wrong. What events and webhooks are is in Events and webhooks. How to make a request to OS (address, sign-in, pages, errors) is in The access API.

Reading the feed¶

curl -s "$OS/api/v1/organisations/$ORG/events?limit=100" -H "Authorization: Bearer $TOKEN"

{"items": [
   {"id": "evt_...", "type": "directory.invitation.created", "organisation_id": "org_...",
    "cursor": "41", "created_at": "2026-10-17T09:14:03Z", "refs": {"invitation_id": "inv_..."}}
 ],
 "next_cursor": "41"}

• Without cursor you start at the oldest event OS still keeps. Handle the page, keep next_cursor, and ask ?cursor= with that value next time.
• next_cursor is there on a short page too: it then points past everything OS has recorded so far, the kinds you left out with types included. When nothing is new, you get an empty page and the same next_cursor; ask again later.
• types narrows the feed to some kinds: ?types=directory.membership.removed.
• limit is at most 100. A page can hold fewer events than limit while next_cursor continues: you see only what you may see.
• 410 means the events after your cursor are no longer kept. Read the current state again and start without a cursor.

You need see on event.

Registering a webhook¶

curl -s -X POST "$OS/api/v1/organisations/$ORG/webhooks" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://crm.example.com/os-events", "label": "CRM",
       "kinds": ["directory.membership.created", "directory.membership.removed"],
       "actor_membership_id": "mem_..."}'

{"id": "whk_...", "label": "CRM", "url": "https://crm.example.com/os-events",
 "kinds": ["directory.membership.created", "directory.membership.removed"],
 "actor_membership_id": "mem_...", "state": "active", "consecutive_failures": 0,
 "allowed_actions": ["see", "write", "delete"], "secret": "whsec_..."}

• Store secret straight away. OS shows the secret only in this answer, and never again.
• An empty kinds means every kind, including kinds added later.
• actor_membership_id is the account the webhook receives as: an active member of your organisation that you may change and whose every grant you hold yourself.
• An organisation has at most 20 webhooks.

Changing, replacing, removing¶

These requests need write on webhook (removing delete, reading see).

Receiving a delivery¶

OS sends each event as a POST with the event as JSON and these headers:

Answer with a 2xx as soon as you have stored the event safely; do the work afterwards. OS waits at most 10 seconds for your answer and does not read its content. Another status, a redirect or no answer counts as failed, and OS tries again.

You can receive the same delivery more than once, for example when your answer got lost on the way. Drop a delivery whose Idempotency-Key you already handled.

Check the signature¶

The signature is the HMAC-SHA256 of the time, a dot and the exact content, under the secret, as hexadecimal. Accept a delivery when one of the v1 values matches and the time is no more than five minutes off:

import hashlib, hmac, time

def is_from_os(secret: str, header: str, body: bytes) -> bool:
    parts = [part.split("=", 1) for part in header.split(",")]
    timestamp = next(value for key, value in parts if key == "t")
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    signed = any(hmac.compare_digest(expected, value) for key, value in parts if key == "v1")
    return signed and abs(time.time() - int(timestamp)) <= 300

Check the raw content as you received it, not JSON you built again. The same function also checks the webhooks of the AI features, which are signed the same way.

During a replacement with an overlap every delivery carries two v1 values, the new one first. Put the new secret in your program whenever it suits you, while the overlap lasts.

The delivery log¶

curl -s "$OS/api/v1/organisations/$ORG/webhooks/$WEBHOOK/deliveries?state=failed" \
  -H "Authorization: Bearer $TOKEN"

Each delivery has state (queued, sending, delivered, failed or skipped), attempts, last_status, last_error (timeout, connect, tls, host_refused, redirect), and for a skipped delivery skipped_reason:

POST .../deliveries/{delivery_id}/redeliver sends a finished delivery again, with the same Idempotency-Key, while its event is kept; 409 while it still waits or is being sent. To replay a whole stretch, read the feed from your last cursor.