Webhooks API

GET/v1/webhooks

List the workspace's outbound webhook endpoints. The signing secret is never included in this response; it is shown only once, at creation. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused.

curl "https://api.brixsignage.com/v1/webhooks" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/webhooks

Create an endpoint. The response includes the signing secret once; after that, only a preview of it is available, since it is stored encrypted and cannot be retrieved in full. The endpoint URL is checked at creation and again before every delivery, since a hostname that resolved to a public address at save time could later be re-pointed at an internal address. Only content.recalled and content.restored events are actually sent today, even though the event catalog lists more. The response carries the signing secret ONCE. Store it: later reads return only secretPreview. **Notes.** - Validation failures are 400 bad_request, where most other routes answer 422 validation_error.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/webhooks" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/brix","events":["screen.offline","screen.online"],"description":"Ops alerts"}'

Response 201 Success.

{
  "data": {
    "id": "whe_7a8b9c0d1e2f3a4b",
    "url": "https://hooks.example.com/brix",
    "description": "Ops alerts",
    "secretPreview": "3f9a1c2e",
    "events": [
      "screen.offline",
      "screen.online"
    ],
    "enabled": true,
    "autoDisabledAt": null,
    "autoDisabledReason": null,
    "consecutiveFailures": 0,
    "lastDeliveryAt": null,
    "lastStatus": null,
    "createdAt": "2026-09-28T09:00:00.000Z",
    "updatedAt": "2026-09-28T09:00:00.000Z",
    "secret": "3f9a1c2e4b5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f"
  }
}

Response 400 `bad_request` (missing url, unknown event) or `unsafe_url`.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

PATCH/v1/webhooks/{id}

Change a webhook endpoint's URL, event subscriptions, description, or enabled state. Re-enabling an endpoint clears any automatic disable and resets its failure count, since re-enabling means the receiver has been confirmed fixed. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused. - Validation failures are 400 bad_request, where most other routes answer 422 validation_error.

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/webhooks/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Response 200 Success.

{
  "data": {
    "id": "whe_7a8b9c0d1e2f3a4b",
    "url": "https://hooks.example.com/brix",
    "description": "Ops alerts",
    "secretPreview": "3f9a1c2e",
    "events": [
      "screen.offline",
      "screen.online"
    ],
    "enabled": true,
    "autoDisabledAt": null,
    "autoDisabledReason": null,
    "consecutiveFailures": 0,
    "lastDeliveryAt": null,
    "lastStatus": null,
    "createdAt": "2026-09-28T09:00:00.000Z",
    "updatedAt": "2026-09-28T09:00:00.000Z"
  }
}

Response 400 `bad_request` (unknown event) or `unsafe_url`.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such endpoint in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/webhooks/{id}

Delete a webhook endpoint. Any deliveries still pending for it are abandoned rather than retried. **Notes.** - Answers { data: { id } } — without the deleted: true most other deletes return.

curl -X DELETE "https://api.brixsignage.com/v1/webhooks/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such endpoint in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/webhooks/{id}/test

Send a real, signed sample delivery to this endpoint now. It is a genuine delivery rather than a simulation, so it exercises the same signature verification your receiver uses in production. The sample event is screen.offline; this call returns 409 if the endpoint is not subscribed to that event. Sends a real, signed screen.offline delivery with data: { test: true, note } now and records it in the delivery log. A failed send is NOT an HTTP error: the answer is 200 with ok: false. **Notes.** - The test event is always screen.offline: an endpoint subscribed only to other events gets 409 not_subscribed, with a message that says it is subscribed to no event. - Needs the permission at the workspace root: a location-scoped key is refused.

curl -X POST "https://api.brixsignage.com/v1/webhooks/{id}/test" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such endpoint in this workspace.

Response 409 `not_subscribed`: the endpoint is not subscribed to `screen.offline`, or it is switched off.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/webhooks/deliveries

List the webhook delivery log: what was sent, the response received, the number of attempts, and what is still pending. Each entry includes the exact payload that was sent. Results are paginated and can be filtered by endpoint and status. Failed deliveries are retried with increasing delay over roughly 8 to 12 hours before they are given up on. **Notes.** - Always paged: without ?limit a page has 50 deliveries (not every row, unlike the lists that page only on request), and nextCursor is always present. - Needs the permission at the workspace root: a location-scoped key is refused.

curl "https://api.brixsignage.com/v1/webhooks/deliveries" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/webhooks/deliveries/{id}/replay

Resend a delivery as a new delivery with its own id and a replayOf field pointing at the original. The original delivery record is left unchanged, so a receiver that deduplicates on delivery id will not silently ignore the resend. Sends the payload again now, as a new delivery. A failed send is NOT an HTTP error: the answer is 200 with ok: false. **Notes.** - Needs the permission at the workspace root: a location-scoped key is refused.

curl -X POST "https://api.brixsignage.com/v1/webhooks/deliveries/{id}/replay" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such delivery in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/webhooks/events

List the catalog of event types that can be subscribed to, each with a label and a description of what it carries. Only content.recalled and content.restored events are actually sent today; other listed events are not yet emitted.

curl "https://api.brixsignage.com/v1/webhooks/events" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.