Webhooks

Webhooks allow you to receive HTTP callbacks when events occur in your Snaapi application. Configure webhook subscriptions with event pattern matching, custom headers, field filtering, and automatic retry with exponential backoff.

Subscriptions

A webhook subscription defines where and how event notifications are delivered:

Event Patterns

Event patterns use wildcards to match one or more event types:

Pattern names must match the regex ^[a-zA-Z0-9_.*]+$.

Custom Headers

Add custom HTTP headers to webhook deliveries for authentication or routing:

{
  "headers": {
    "Authorization": "Bearer my-secret-token",
    "X-Custom-Header": "custom-value"
  }
}

The following headers are always included automatically:

Field Filtering

Use fieldIds to limit which fields are included in the webhook payload. When specified, only the listed fields (by ID) are included in a fields object:

{
  "fields": {
    "title": {
      "id": "field-id",
      "type": "string",
      "value": "Hello World"
    }
  }
}

If fieldIds is null or omitted, no fields object is included in the payload.

Webhook Payload

The full payload delivered to your endpoint:

{
  "id": "event-uuid",
  "event": {
    "type": "posts.created",
    "resource": "posts",
    "resourceId": "post-123",
    "createdAt": "2026-01-01T00:00:00Z",
    "data": {
      "old": null,
      "new": { "id": "post-123", "title": "Hello World" },
      "changes": { "added": ["id", "title"], "updated": [], "removed": [] }
    },
    "sessionVariables": { "userId": "user-1", "role": "editor" },
    "traceContext": { "traceId": "abc", "requestId": "req-1" }
  },
  "delivery": {
    "id": "delivery-uuid",
    "attempt": 1
  }
}

Delivery timeout is 30 seconds.

Retry Configuration

Webhooks use exponential backoff for failed deliveries. Customize retry behavior per webhook or use the defaults:

The delay between retries is calculated as:

delay = min(initialDelayMs * backoffMultiplier ^ (attempt - 1), maxDelayMs)

Delivery Tracking

Each webhook delivery attempt is recorded as a WebhookDelivery:

Delivery Statuses