SeatBuilderSeatBuilder Docs
Webhooks

Create a webhook endpoint

Registers a webhook endpoint and returns the new `id` and signing `secret`. The secret is shown ONCE — store it server-side to verify the HMAC-SHA256 signature on incoming payloads. Subsequent reads omit the secret; use `/rotate-secret` to mint a new one.

POST/api/v1/webhooks

Request Body

urlstring

HTTPS endpoint that will receive webhook POST requests. Must be reachable from the Seats platform (no localhost, no private IP ranges — see the SSRF guard in aes-gcm.ts). Maximum length 2048 chars.

Formaturi
Lengthlength <= 2048
eventsarray<string>

List of event types this endpoint subscribes to. Choose from seat.held, seat.booked, seat.released, seat.hold_expired. At least one is required.

Items1 <= items
description?string

Optional human-readable description (≤ 255 chars). Surfaces in the dashboard webhooks list and dev tools.

Lengthlength <= 255

Response Body

curl -X POST "http://localhost:3000/api/v1/webhooks" \  -H "Content-Type: application/json" \  -d '{    "url": "http://example.com",    "events": [      "seat.held"    ]  }'

{
  "id": "wh_2a8f1d",
  "url": "https://api.brooklynmusichall.example/seats-webhook",
  "events": [
    "seat.held",
    "seat.booked",
    "seat.released"
  ],
  "description": "Production order pipeline",
  "enabled": true,
  "secret": "whsec_4a9c08fe1b3d7e5a6f0c2b9e8d1a4c7b",
  "createdAt": "2026-09-12T14:22:01.044Z",
  "updatedAt": "2026-09-12T14:22:01.044Z"
}
{
  "statusCode": 0,
  "message": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
{
  "statusCode": 0,
  "message": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}
{
  "statusCode": 0,
  "message": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Get a webhook endpoint GET

Returns a single webhook endpoint by `id`. Signing secret is not included; use `/rotate-secret` to mint a fresh one.

Update a webhook endpoint PATCH

Updates a webhook endpoint's `url`, `events`, `enabled`, or `description`. The `events` array REPLACES the current subscription list (not merged). At least one field is required.