API reference

Webhook subscriptions

Addresses the books' events are sent to as they happen, signed, with each delivery and its tries.

GET/v1/webhook_subscriptionsList the addresses the books send events to
POST/v1/webhook_subscriptionsSend the books' events to an address
GET/v1/webhook_subscriptions/{subscription_id}Get a webhook subscription
PATCH/v1/webhook_subscriptions/{subscription_id}Change a webhook subscription, or switch it off and on
DELETE/v1/webhook_subscriptions/{subscription_id}Delete a webhook subscription
GET/v1/webhook_subscriptions/{subscription_id}/deliveriesList what was sent to a subscription
GET/v1/webhook_subscriptions/{subscription_id}/secretGet the secret a subscription's deliveries are signed with
POST/v1/webhook_subscriptions/{subscription_id}/testSend a test event to a subscription

Guides: Webhooks

List the addresses the books send events to

GET/v1/webhook_subscriptions

client.webhookSubscriptions.list()

The addresses these books send their events to, the newest first.

Parameters

Name	Type	Description
`enabled`Query	boolean or null	Only those switched on (`true`) or off (`false`).
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200WebhookSubscriptionPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/webhook_subscriptions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Send the books' events to an address

POST/v1/webhook_subscriptions· Idempotent

client.webhookSubscriptions.create()

Send these books' events to an https address. Every event from now on that it wants is POSTed to it, signed with its secret (read it with GET /webhook_subscriptions/{id}/secret), and retried until the address answers 2xx.

Request body

WebhookSubscriptionCreate

Response

201WebhookSubscriptionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/webhook_subscriptions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"…"}'

Get a webhook subscription

GET/v1/webhook_subscriptions/{subscription_id}

client.webhookSubscriptions.get()

One webhook subscription.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.

Response

200WebhookSubscriptionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Change a webhook subscription, or switch it off and on

PATCH/v1/webhook_subscriptions/{subscription_id}

client.webhookSubscriptions.update()

Change a subscription's address, description or events, or switch it off and on. Only the fields sent change.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.

Request body

WebhookSubscriptionUpdate

Response

200WebhookSubscriptionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a webhook subscription

DELETE/v1/webhook_subscriptions/{subscription_id}

client.webhookSubscriptions.delete()

Stop sending events to an address, for good. Its deliveries still waiting go with it.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

List what was sent to a subscription

GET/v1/webhook_subscriptions/{subscription_id}/deliveries

client.webhookSubscriptions.listDeliveries()

What has been sent to a subscription, and what is waiting, the newest first: each event, how many tries, and why the last one failed.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.
`status`Query	string or null	Only `pending` or `delivered` deliveries. One of `pending`, `delivered`
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200WebhookDeliveryPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}/deliveries" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Get the secret a subscription's deliveries are signed with

GET/v1/webhook_subscriptions/{subscription_id}/secret

client.webhookSubscriptions.getSecret()

The secret a subscription's deliveries are signed with, to check the LedgerIt-Signature header against.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.

Response

200WebhookSecret

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}/secret" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Send a test event to a subscription

POST/v1/webhook_subscriptions/{subscription_id}/test· Idempotent

client.webhookSubscriptions.test()

Send a webhook.test event to this subscription alone, to see its address answer. It is queued like any delivery and listed with them.

Parameters

Name	Type	Description
`subscription_id`Path · Required	string	An id that starts with `whsub_`.

Response

201WebhookDeliveryOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/webhook_subscriptions/{subscription_id}/test" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Objects

The objects these operations take and return.

WebhookSubscriptionPage

Name	Type	Description
`data`Required	array of WebhookSubscriptionOut
`has_more`Required	boolean
`next_cursor`Required	string or null

WebhookSubscriptionCreate

Name	Type	Description
`description`	string or null	What it is for.
`event_types`	array of string	The events to send: types such as `entry.posted`, or families such as `entry.*`. Empty sends every event. Default []
`url`Required	string	An https address.

WebhookSubscriptionOut

Name	Type	Description
`created_at`Required	string (date-time)
`description`Required	string or null	What it is for, as its maker put it.
`disabled_reason`Required	string or null	Why it is off: `person` when someone switched it off, `failing` when its deliveries failed for three days. Null while it is on. One of `person`, `failing`
`enabled`Required	boolean	Whether events are being sent to it.
`event_types`Required	array of string	The event types and families it is sent. Empty: every event.
`failing_since`Required	string (date-time) or null	The first failure since a delivery last landed. Null while deliveries land.
`id`Required	string	An id that starts with `whsub_`.
`updated_at`Required	string (date-time)
`url`Required	string	The https address events are POSTed to.

WebhookSubscriptionUpdate

Name	Type	Description
`description`	string or null	What it is for. An empty string clears it.
`enabled`	boolean or null	Switch it off, or back on. Back on, the deliveries that waited are sent at once.
`event_types`	array of string or null	The events to send: types such as `entry.posted`, or families such as `entry.*`. Empty sends every event.
`url`	string or null	A new https address.

WebhookDeliveryPage

Name	Type	Description
`data`Required	array of WebhookDeliveryOut
`has_more`Required	boolean
`next_cursor`Required	string or null

WebhookSecret

Name	Type	Description
`secret`Required	string	What each delivery is signed with: the `LedgerIt-Signature` header is the HMAC-SHA256 of `<t>.<body>` under it.

WebhookDeliveryOut

Name	Type	Description
`attempts`Required	integer	Times it has been tried.
`created_at`Required	string (date-time)
`delivered_at`Required	string (date-time) or null
`event_id`Required	string	The event, and the `id` of the body sent.
`event_type`Required	string	What happened, such as `entry.posted`.
`id`Required	string	An id that starts with `dlv_`.
`last_error`Required	string or null	Why the last try failed, such as `HTTP 500`.
`next_attempt_at`Required	string (date-time) or null	When it is tried next, while pending.
`status`Required	string	`pending` until the address answers 2xx, then `delivered`. One of `pending`, `delivered`