Light AIDocs Beta Open Light AI

API reference

POSTRotate the signing secret

POST /v1/webhook_endpoints/{endpoint_id}/rotate_secret: Returns the new secret once.

POSThttps://api.light-ai.app/v1/webhook_endpoints/{endpoint_id}/rotate_secret

Returns the new secret once. For 24 hours deliveries carry signatures for both secrets.

Scopewebhooks:manage
CredentialAPI key: Authorization: Bearer lai_live_… (or lai_test_…). Partner keys add Light-AI-Organization.
Test modeWorks with test keys (test objects only).
IdempotencyIdempotency-Key supported. See Idempotency.

Path parameters#

endpoint_idstringrequired#
The endpoint id (we_…). Id prefix we_.

Headers#

Light-AI-Organizationstring#
Partner keys: the connected organization to act for (org_…). Organization keys may omit it. Id prefix org_.
Light-AI-Versionstring#
Pin a dated API version (defaults to the key's version). One of: 2026-11-01.
Idempotency-Keystring#
Retry-safe writes: the same key and body replay the first response for 24 hours (Idempotent-Replayed: true). 8–128 characters.

Request body#

An empty JSON object ({}) or no body.

Response 200#

The endpoint with its new secret.

idstringrequired#
Id prefix we_.
objectstringrequired#
Always webhook_endpoint.
urlstringrequired#
descriptionstring | nullrequired#
eventsstring[]required#
One of: lead.created, lead.touched, lead.updated, lead.mockup_ready, client.created, client.updated, client.deleted, project.created, project.stage_changed, quote.published, quote.viewed, quote.external_link_clicked, quote.change_requested, quote.approved, quote.declined, quote.expired, quote.link_disabled, quote.link_enabled, quote.superseded, mockup.completed, mockup.failed, organization.entitlement_changed, grant.created, grant.revoked, api_key.expiring, webhook_endpoint.disabled, ping.
unentitled_eventsstring[]required#
Subscribed types the organization's current plan does not deliver live (e.g. after a downgrade). They resume when the plan includes them. One of: lead.created, lead.touched, lead.updated, lead.mockup_ready, client.created, client.updated, client.deleted, project.created, project.stage_changed, quote.published, quote.viewed, quote.external_link_clicked, quote.change_requested, quote.approved, quote.declined, quote.expired, quote.link_disabled, quote.link_enabled, quote.superseded, mockup.completed, mockup.failed, organization.entitlement_changed, grant.created, grant.revoked, api_key.expiring, webhook_endpoint.disabled, ping.
livemodebooleanrequired#
false for objects created with a test key.
statusstringrequired#
One of: enabled, disabled, disabled_by_system, disabled_by_revocation, suspended.
status_reasonstring | nullrequired#
Why it is not enabled. disabled_by_organization: the contractor disabled it in Settings → Developers. Until they enable it there (it then returns to the state it had before their disable) or remove it there, the API cannot enable, re-point or delete it, nor create or point another endpoint at the same receiver (the same host, port and path; query string, case, repeated or trailing slashes and :443 ignored): each answers 409 stale_state with current_state disabled_by_organization. A partner's partner-level endpoints at that receiver receive none of that contractor's events meanwhile (its organization.entitlement_changed included; grant notices addressed to the partner still arrive). A different path or host is a different receiver. This stops deliveries, not access: a partner's key still reads through its grant (the contractor suspends or revokes the grant to stop the partner). gone / circuit_breaker: Light AI stopped it (410, or 72 hours of failures). grant_suspended, grant_revoked, key and security reasons: access was suspended or revoked.
disabled_while_suspendedbooleanrequired#
api_versionstringrequired#
exclude_own_originbooleanrequired#
scopesstring[]required#
One of: leads:read, leads:write, clients:read, clients:write, projects:read, projects:write, quotes:read, quotes:write, quotes:share_link, quotes:asset_links, webhooks:manage, events:read, mockups:read, mockups:write, forms:read, forms:write.
kindstringrequired#
One of: organization, partner.
grant_idsstring[] | nullrequired#
static_headerobject | nullrequired#
static_header.namestringrequired#
static_header.value_redactedstringrequired#
… plus the last 4 characters of a value of 12 or more characters; … alone for a shorter value.
created_byobjectrequired#
created_by.typestringrequired#
One of: api_key, user.
created_by.idstring | nullrequired#
created_by.namestring | nullrequired#
created_by.partnerstring | null#
lanestringrequired#
One of: normal, degraded.
backlogintegerrequired#
oldest_pending_attimestamp | nullrequired#
RFC 3339 timestamp (UTC, milliseconds).
last_success_attimestamp | nullrequired#
RFC 3339 timestamp (UTC, milliseconds).
last_failure_attimestamp | nullrequired#
RFC 3339 timestamp (UTC, milliseconds).
created_attimestamprequired#
RFC 3339 timestamp (UTC, milliseconds).
updated_attimestamprequired#
RFC 3339 timestamp (UTC, milliseconds).
secretstring#
The signing secret (whsec_…). Returned only when created, re-subscribed or rotated.

Errors#

StatusMeaning
400Bad request. bad_request, test_mode_mismatch, test_mode_unsupported, unsupported_api_version
401Missing or invalid credential. authentication_required, invalid_api_key, api_key_revoked, api_key_expired, api_key_suspended
403Not allowed. insufficient_scope, plan_upgrade_required, organization_paused, organization_off_season, api_disabled, api_access_not_enabled, ip_not_allowed, forbidden
404Not found (also for objects of other organizations and for organizations without an active grant).
409Conflict. stale_state, conflict, idempotency_in_progress, idempotency_scope_mismatch, quote_already_decided, quote_not_current, billing_review_required
413Request bodies are limited to 256 KB.
415The body is not JSON: send Content-Type: application/json. unsupported_media_type
422Validation failed. idempotency_key_reused
429Rate limited or daily cap reached. See Retry-After and the RateLimit headers. rate_limited, daily_cap_reached
500Unexpected server error. Safe to retry with exponential backoff; quote the Request-Id to support. internal_error
503Temporarily unavailable. Retry with exponential backoff. service_unavailable