API reference

Webhooks

Subscribe to real-time events when optimizations change status, products are scored, or syncs complete. Webhooks are delivered as POST requests to your URL.

The webhook model

The webhook model contains the endpoint URL, subscribed events, signing secret, and delivery status information.

Field	Type	Description
id	string
url	string
events	string[]
status	string
failure_count	integer
last_triggered_at	string
created_at	string
updated_at	string
last_success_at	string
last_failure_at	string
last_error	string

Available events

optimization.created
optimization.approved
optimization.rejected
optimization.applied
optimization.reverted
product.scored
product.synced

GET /v1/webhooks

List webhooks

Returns webhooks registered for the current API key

Request GET /v1/webhooks

curl -G \
  https://beaconed.ai/api/v1/webhooks \
  -H "Authorization: Bearer {token}"

POST /v1/webhooks

Create a webhook

Creates a new webhook subscription

Required attributes

Attribute	Type	Description
url	string Required	HTTPS URL to receive webhook deliveries
events	string[] Required	Events to subscribe to

Request POST /v1/webhooks

curl -X POST \
  https://beaconed.ai/api/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"webhook": {"url": "https://example.com/webhooks", "events": ["optimization.applied", "product.scored"]}}'

Response

{
  "success": true,
  "data": {
    "id": "wh-uuid",
    "url": "https://example.com/webhooks",
    "events": ["optimization.applied", "product.scored"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6...",
    "created_at": "2026-03-31T10:00:00Z"
  }
}

GET /v1/webhooks/{id}

Get a webhook

Returns details about a webhook subscription

Request GET /v1/webhooks/{id}

curl https://beaconed.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer {token}"

PATCH /v1/webhooks/{id}

Update a webhook

Updates a webhook subscription

Optional attributes

Attribute	Type	Description
url	string
events	string[]
status	string

Request PATCH /v1/webhooks/{id}

curl -X PATCH \
  https://beaconed.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"webhook": {"events": ["optimization.applied"]}}'

DELETE /v1/webhooks/{id}

Delete a webhook

Removes a webhook subscription

Request DELETE /v1/webhooks/{id}

curl -X DELETE \
  https://beaconed.ai/api/v1/webhooks/{id} \
  -H "Authorization: Bearer {token}"

POST /v1/webhooks/{id}/test

Test a webhook

Sends a test event to the webhook

Request POST /v1/webhooks/{id}/test

curl -X POST \
  https://beaconed.ai/api/v1/webhooks/{id}/test \
  -H "Authorization: Bearer {token}"

GET /v1/webhooks/events

List webhook events

Returns all available webhook events

Request GET /v1/webhooks/events

curl https://beaconed.ai/api/v1/webhooks/events \
  -H "Authorization: Bearer {token}"