Webhook And Event Catalog

This page documents the event surfaces that currently exist for organization-facing integrations.

Current Event Surfaces

There are two operator-facing event surfaces today:

• outbound webhooks configured per organization
• authenticated server-sent events for organization notifications

Outbound Webhook Configuration

Configuration fields:

Only organization owner and admin members can change this config or send a test event.

Current Webhook Event Catalog

notification.created

Emitted when an organization notification is created and outbound delivery is enabled for that event.

Payload shape:

{
  "id": "delivery-uuid",
  "type": "notification.created",
  "createdAt": "2026-03-12T10:00:00.000Z",
  "test": false,
  "organization": {
    "id": "organization-uuid",
    "name": "Acme"
  },
  "data": {
    "notification": {
      "id": "notification-uuid",
      "title": "Title",
      "message": "Message",
      "level": "info",
      "createdAt": "2026-03-12T10:00:00.000Z",
      "expiresAt": null,
      "metadata": {
        "source": "example"
      }
    }
  }
}

Delivery Contract

Webhook delivery behavior:

• method: POST
• content type: application/json
• timeout: 5 seconds
• user agent: Obelisk-Webhooks/1.0

Headers:

• x-obelisk-event
• x-obelisk-delivery-id
• x-obelisk-timestamp
• x-obelisk-signature when a signing secret exists

Signature Model

When signingSecret is configured, the signature is:

HMAC_SHA256(secret, `${timestamp}.${body}`)

Validation guidance:

1. read x-obelisk-timestamp
2. rebuild the exact JSON body string
3. compute the HMAC
4. compare in constant time
5. reject stale or replayed deliveries using x-obelisk-delivery-id

Test Delivery

The test action sends a synthetic notification.created payload with:

• test: true
• a generated notification title and message
• sample metadata showing source: webhook-test

The result is persisted into lastDelivery in organization metadata.

Failure Behavior

If delivery is disabled or the URL is missing, the recorded delivery result is marked unsuccessful.

If the receiver returns a non-2xx response, the failure message stores the HTTP status and response excerpt.

Notification Stream (SSE)

Authenticated operators can also subscribe to:

GET /api/organization/notifications/stream

Current behavior:

• requires a valid signed-in session
• requires activeOrganizationId in session
• verifies the user is a member of the active organization
• sends connected and update events
• polls for snapshot changes every 2.5 seconds
• emits keepalives every 15 seconds
• rotates the stream around 55 seconds to avoid network idle timeouts

SSE Event Names

• connected
• update

The stream is intended for operator-facing clients, not anonymous consumers.

When To Use Which Surface

Related Pages

• Webhooks and Integrations
• Reference Overview
• Public API Reference
• Production Readiness