Manage subscriptions

Use the Webhooks API when subscription setup must be repeatable across customer provisioning, environments, or deployment pipelines. One-off integrations can use the dashboard over the same underlying resources.

Authentication

Secret keys have organization authority. Dashboard reads allow signed-in members; writes require an admin. Event-scoped manage tokens cannot access webhook configuration.

Create a subscription

curl -sX POST "https://api.seatlayer.io/v1/webhooks" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/seatlayer",
    "events": [
      "seat.booked",
      "seat.released",
      "event.soldout"
    ]
  }'

The URL must use HTTPS and events must be a non-empty set of known names.

{
  "sub": {
    "id": "sub_8a2f",
    "url": "https://example.com/webhooks/seatlayer",
    "events": ["seat.booked", "seat.released", "event.soldout"],
    "disabled": false,
    "lastStatus": null,
    "lastAt": null,
    "createdAt": 1761436800000,
    "mode": "live",
    "environment": "prod",
    "uptime7d": null
  },
  "secret": "whsec_1f8c"
}

Scope delivery

Subscriptions can filter by mode and environment.

• A secret-key create inherits that key’s mode and environment.
• A dashboard-session create defaults to live mode and accepts an optional environment.
• A null field is a wildcard after patching.

{
  "url": "https://staging.example.com/webhooks/seatlayer",
  "events": ["seat.booked"],
  "mode": "test",
  "environment": "staging"
}

A secret key cannot use request fields to escape its own routing scope.

Update or pause

Send only changed fields. events replaces the full set.

{
  "events": [
    "seat.booked",
    "seat.released",
    "hold.created",
    "hold.expired"
  ],
  "disabled": true
}

Pause with disabled: true while repairing a receiver. Existing delivery history remains available. Send mode: null or environment: null to restore the wildcard for that axis.

Send a test

With no body, SeatLayer sends a signed ping and waits up to five seconds:

{
  "status": 200,
  "ok": true,
  "event": "ping",
  "responseBody": null
}

You can also request a representative payload:

{
  "event": "seat.booked"
}

Representative tests are available for seat booked/released/blocked, hold created/expired, and event created/sold-out branches. Exercise hold.extended using a test-mode event. Test requests carry test: true, are delivered inline, and are not written to the normal delivery ledger.

Inspect deliveries

Query parameters:

Cursor pages can overlap at the timestamp boundary; de-duplicate by delivery id. Each record includes status, attempt count, retry state, occurrence id, stored payload, and—on failure—a truncated receiver response or transport error.

Retry one delivery

This sends the stored payload to that subscription only. It keeps the original occurrenceId, creates a new delivery attempt and signature, and does not restart the automatic retry chain.

Delete

Deletion removes the subscription. If temporary downtime is expected, prefer disabled: true so configuration and history remain available.

Continue to event payloads, delivery and retries, and signature verification.