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.

Properties

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

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

  • Name
    url
    Type
    string
    Required
    Description
    HTTPS URL to receive webhook deliveries
  • Name
    events
    Type
    string[]
    Required
    Description
    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

  • Name
    url
    Type
    string
    Description
  • Name
    events
    Type
    string[]
    Description
  • Name
    status
    Type
    string
    Description

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}"