Webhooks
Subscriptions, and the event feed you can poll instead.
Every endpoint needs Authorization: Bearer lk_live_.... See
Conventions for headers, status codes
and error shape.
List webhooks
GET /v1/webhooks · scope webhooks:read
Returns the calling tenant’s webhook subscriptions. Never returns the signing secret, only metadata.
Response 200
Webhook list.
| Field | Type | Notes |
|---|---|---|
data |
array of Webhook | Required. |
Errors: 401, 403
Create a webhook
POST /v1/webhooks · scope webhooks:write
Subscribes a URL to one or more event types. Returns the
signing_secret ONCE in the response, store it immediately.
Every outbound POST is signed:
X-Lockally-Signature: t=<unix>,v1=<hex(hmac_sha256(secret, t + “.” + body))>
Verify on your end using HMAC-SHA256 with a 5-minute timestamp window (replay protection). A reference verifier ships in Signature verification.
Event names: see the event catalogue.
Request body
| Field | Type | Notes |
|---|---|---|
url |
string | Required. HTTPS recommended (HTTP allowed for local development). |
events |
array of string | Required. |
Response 201
Created. signing_secret is in the response ONLY here.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
url |
string | Required. |
events |
array of string | Required. |
paused |
boolean | Required. |
paused_at |
string | |
last_success_at |
string | |
last_failure_at |
string | |
consecutive_failures |
integer | Required. |
created_at |
string | Required. |
signing_secret |
string | Hex-encoded HMAC-SHA256 key. Present ONLY on POST response. |
Errors: 400, 401, 403
Update a webhook
PATCH /v1/webhooks/{id} · scope webhooks:write
Supply at least one of url, events, paused. Setting paused
to false ALSO resets consecutive_failures to 0, re-arms the
50-failure auto-pause counter.
Request body
| Field | Type | Notes |
|---|---|---|
url |
string | |
events |
array of string | |
paused |
boolean |
Response 200
Updated webhook.
| Field | Type | Notes |
|---|---|---|
id |
string | Required. |
tenant_id |
string | Required. |
url |
string | Required. |
events |
array of string | Required. |
paused |
boolean | Required. |
paused_at |
string | |
last_success_at |
string | |
last_failure_at |
string | |
consecutive_failures |
integer | Required. |
created_at |
string | Required. |
signing_secret |
string | Hex-encoded HMAC-SHA256 key. Present ONLY on POST response. |
Errors: 400, 401, 403, 404
Delete a webhook
DELETE /v1/webhooks/{id} · scope webhooks:write
Hard-delete; cascades to webhook_deliveries history.
Response 204
Deleted.
Errors: 401, 403, 404