BoxLatviaDevelopers
Get access
API reference

Webhooks

Manage the addresses BoxLatvia calls when something happens. How the events look, how to verify them and how delivery works is in the Webhooks guide.

#The Webhook object

NameTypeDescription
iduuidBoxLatvia's identifier of the webhook.
urlstringWhere BoxLatvia sends the events.
descriptionstring | nullYour note, up to 200 characters.
eventsstring[]The events you receive: order.placed, order.cancelled, box.availability_changed.
statusstringactive, paused (by you), or disabled (switched off automatically after 30 failed attempts in a row). Set it to active to switch it on again.
consecutive_failuresintegerFailed attempts in a row. Reset by a success.
disabled_reason disabled_atstring | null, datetime | nullWhy and when it was switched off automatically.
last_success_at last_failure_atdatetime | nullISO 8601, UTC.
created_at updated_atdatetimeISO 8601, UTC.

When a webhook is created, the answer also has secret: the signing secret, shown only once.

#The Delivery object

NameTypeDescription
idstringdlv_…. Also sent to you as the BoxLatvia-Delivery-Id header.
event_idstringevt_…: the id in the body of the event. Use it to ignore duplicates.
event_typestringorder.placed, order.cancelled, box.availability_changed or webhook.test.
statusstringpending (waiting for a first or next attempt), succeeded, failed (given up after 8 attempts) or cancelled (the webhook was paused or switched off).
attemptsintegerAttempts made.
next_attempt_atdatetime | nullWhen the next attempt is due (only while pending).
last_attempt_at delivered_at created_atdatetime | nullISO 8601, UTC.
last_status_codeinteger | nullThe HTTP status your address answered with.
last_errorstring | nullWhy the last attempt failed: a short text, never your answer.
last_duration_msinteger | nullHow long the last attempt took.

#Endpoints

#Subscribe to events

POST/v1/webhookswebhooks:write

Registers an address that BoxLatvia calls when the chosen events happen. The answer contains the signing secret, shown only once.

  • Store the secret now: it is never shown again (you can replace it). It is used to verify the signature of every event.
  • You can have at most 10 webhooks. The same url cannot be registered twice.
  • A response that contains a secret is never replayed by Idempotency-Key.

Query parameters

NameTypeDescription
validate_onlybooleantrue runs every check and returns what would happen, but saves nothing. See dry runs.

Headers

NameTypeDescription
Idempotency-KeystringOptional. 1 to 200 printable characters. A retry with the same key returns the original result instead of repeating the action. See safe retries.

Request body

NameTypeDescription
url requiredstringRequired when creating. https only, a public host name (not an IP address), port 443 or 8443, no user name or password.
events requiredstring[]Required when creating. At least one of order.placed, order.cancelled, box.availability_changed. The two order events contain the renter's contact details, so they also need the scope orders:read.
descriptionstring | nullOptional note, up to 200 characters.
statusstringOnly when updating: active or paused.

Examples

Availability and orders
curl -X POST "$API/v1/webhooks" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "events": [
    "order.placed",
    "order.cancelled",
    "box.availability_changed"
  ],
  "description": "Imanta ERP"
}'
201 CreatedLocation: https://api.boxlatvia.lv/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9
{
  "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "description": "Imanta ERP",
  "events": [
    "order.placed",
    "order.cancelled",
    "box.availability_changed"
  ],
  "status": "active",
  "consecutive_failures": 0,
  "disabled_reason": null,
  "disabled_at": null,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-11-14T09:00:01.000Z",
  "updated_at": "2026-11-14T09:00:01.000Z",
  "secret": "whsec_8Fh2kQ0pXm4TnV7cYd1LrB9sAe5ZuWjG"
}
Invalid values
curl -X POST "$API/v1/webhooks" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "http://localhost/hook",
  "events": [
    "order.shipped"
  ]
}'
422 Unprocessable Content
{
  "type": "https://api.boxlatvia.lv/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "request_id": "9152c9a2-22bb-47b3-a96d-cabea1332567",
  "errors": [
    {
      "field": "url",
      "message": "must start with https://"
    },
    {
      "field": "events",
      "message": "unknown event(s): order.shipped. Choose from: order.placed, order.cancelled, box.availability_changed"
    }
  ]
}
Order events need orders:read
curl -X POST "$API/v1/webhooks" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.imantastorage.example/orders",
  "events": [
    "order.placed"
  ]
}'
403 Forbidden
{
  "type": "https://api.boxlatvia.lv/problems/insufficient-scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "The events order.placed and order.cancelled contain the renter's contact details: subscribing to them needs the scope orders:read as well.",
  "request_id": "095a3f1f-26e0-4a60-9552-0dd23b6b1c5f",
  "required_scope": "orders:read"
}
The same address twice
curl -X POST "$API/v1/webhooks" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "events": [
    "box.availability_changed"
  ]
}'
409 Conflict
{
  "type": "https://api.boxlatvia.lv/problems/duplicate-webhook",
  "title": "Conflict",
  "status": 409,
  "detail": "You already have a webhook with this url.",
  "request_id": "a96b81a2-66bd-464d-a821-2b23308f6f23",
  "existing_id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
  "existing": "https://api.boxlatvia.lv/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9"
}

Errors

StatusWhen
403An order event was asked for without the scope orders:read.
409The url is already registered (existing_id), or you have 10 webhooks already (webhook-limit).
422A value is invalid: not https, an IP address or internal host name, an unknown event.

#List webhooks

GET/v1/webhookswebhooks:read

Your webhooks.

Example

Your webhooks
curl "$API/v1/webhooks" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "data": [
    {
      "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
      "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
      "description": "Imanta ERP",
      "events": [
        "order.placed",
        "order.cancelled",
        "box.availability_changed"
      ],
      "status": "active",
      "consecutive_failures": 0,
      "disabled_reason": null,
      "disabled_at": null,
      "last_success_at": null,
      "last_failure_at": null,
      "created_at": "2026-11-14T09:00:01.000Z",
      "updated_at": "2026-11-14T09:00:01.000Z"
    }
  ]
}

#Read a webhook

GET/v1/webhooks/{id}webhooks:read

One webhook. The secret is never included.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Example

A webhook
curl "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "description": "Imanta ERP",
  "events": [
    "order.placed",
    "order.cancelled",
    "box.availability_changed"
  ],
  "status": "active",
  "consecutive_failures": 0,
  "disabled_reason": null,
  "disabled_at": null,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-11-14T09:00:01.000Z",
  "updated_at": "2026-11-14T09:00:01.000Z"
}

Errors

StatusWhen
404No such webhook of yours.

#Change a webhook

PATCH/v1/webhooks/{id}webhooks:write

Changes the address, the events, the note or the status. Send only what changes.

Set status to paused to stop events for a while (events waiting to be sent are cancelled), and to active to start again, also after BoxLatvia switched the webhook off automatically.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Query parameters

NameTypeDescription
validate_onlybooleantrue runs every check and returns what would happen, but saves nothing. See dry runs.

Headers

NameTypeDescription
Idempotency-KeystringOptional. 1 to 200 printable characters. A retry with the same key returns the original result instead of repeating the action. See safe retries.

Request body

NameTypeDescription
url requiredstringRequired when creating. https only, a public host name (not an IP address), port 443 or 8443, no user name or password.
events requiredstring[]Required when creating. At least one of order.placed, order.cancelled, box.availability_changed. The two order events contain the renter's contact details, so they also need the scope orders:read.
descriptionstring | nullOptional note, up to 200 characters.
statusstringOnly when updating: active or paused.

Examples

Pause
curl -X PATCH "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'
200 OK
{
  "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "description": "Imanta ERP",
  "events": [
    "order.placed",
    "order.cancelled",
    "box.availability_changed"
  ],
  "status": "paused",
  "consecutive_failures": 0,
  "disabled_reason": null,
  "disabled_at": null,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-11-14T09:00:01.000Z",
  "updated_at": "2026-11-14T09:00:01.000Z"
}
Change the events
curl -X PATCH "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active",
  "events": [
    "order.placed",
    "box.availability_changed"
  ],
  "description": "Imanta ERP (orders and stock)"
}'
200 OK
{
  "id": "cb3cf942-3e09-4b76-9b89-0143c09a8ae9",
  "url": "https://erp.imantastorage.example/webhooks/boxlatvia",
  "description": "Imanta ERP (orders and stock)",
  "events": [
    "order.placed",
    "box.availability_changed"
  ],
  "status": "active",
  "consecutive_failures": 0,
  "disabled_reason": null,
  "disabled_at": null,
  "last_success_at": null,
  "last_failure_at": null,
  "created_at": "2026-11-14T09:00:01.000Z",
  "updated_at": "2026-11-14T09:00:01.000Z"
}

Errors

StatusWhen
403An order event was asked for without orders:read.
404No such webhook of yours.
409The new url is already registered.
422A value is invalid; status can only be active or paused.

#Delete a webhook

DELETE/v1/webhooks/{id}webhooks:write

Deletes the webhook and its delivery history.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Query parameters

NameTypeDescription
validate_onlybooleantrue runs every check and returns what would happen, but saves nothing. See dry runs.

Headers

NameTypeDescription
Idempotency-KeystringOptional. 1 to 200 printable characters. A retry with the same key returns the original result instead of repeating the action. See safe retries.

Example

Delete
curl -X DELETE "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
204 No Content
No response body

Errors

StatusWhen
404No such webhook of yours.

#Send a test event

POST/v1/webhooks/{id}/testwebhooks:write

Sends a webhook.test event to this address only, signed like a real one. It is tried once; the result appears in the deliveries.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Example

Queue a test
curl -X POST "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/test" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
202
{
  "event_id": "evt_e45a0c9d-e02d-43d0-bc2c-bb9eb9b3cd09",
  "status": "queued",
  "message": "A test event is on its way. See GET /v1/webhooks/{id}/deliveries for the result."
}

Errors

StatusWhen
404No such webhook of yours.

#Replace the secret

POST/v1/webhooks/{id}/rotate-secretwebhooks:write

Creates a new signing secret. The old one keeps working for 24 hours: events are signed with both, so you can switch without missing one.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Query parameters

NameTypeDescription
validate_onlybooleantrue runs every check and returns what would happen, but saves nothing. See dry runs.

Headers

NameTypeDescription
Idempotency-KeystringOptional. 1 to 200 printable characters. A retry with the same key returns the original result instead of repeating the action. See safe retries.

Example

A new secret
curl -X POST "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/rotate-secret" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "secret": "whsec_Qn7wT3zLk0YbR5xVu9HcJd2PaMe6GsFi",
  "previous_secret_valid_until": "2026-11-15T09:00:00.000Z"
}

Errors

StatusWhen
404No such webhook of yours.

#Delivery history

GET/v1/webhooks/{id}/deliverieswebhooks:read

The latest deliveries of a webhook, newest first, with the result of the last attempt. This is where you find out why events do not arrive.

Path parameters

NameTypeDescription
iduuidThe webhook's id.

Query parameters

NameTypeDescription
statusstringpending, succeeded, failed or cancelled.
limitinteger1 to 100. Default 50.

Example

A success and a failure
curl "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/deliveries?limit=10" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
200 OK
{
  "data": [
    {
      "id": "dlv_2ff29879-e014-4073-a557-dc223bc2b152",
      "event_id": "evt_70992594-5e8d-4f77-aa18-b5d5661ec959",
      "event_type": "webhook.test",
      "status": "succeeded",
      "attempts": 1,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-14T09:20:03.000Z",
      "last_status_code": 200,
      "last_error": null,
      "last_duration_ms": 214,
      "delivered_at": "2026-11-14T09:20:03.000Z",
      "created_at": "2026-11-14T09:20:00.000Z"
    },
    {
      "id": "dlv_bf376349-5c7e-40c5-83c4-b19cb4d93561",
      "event_id": "evt_3bb11835-8fb0-49fc-93ff-a7346c491a37",
      "event_type": "box.availability_changed",
      "status": "pending",
      "attempts": 2,
      "next_attempt_at": "2026-11-14T09:21:00.000Z",
      "last_attempt_at": "2026-11-14T09:15:40.000Z",
      "last_status_code": 503,
      "last_error": "the receiver answered HTTP 503",
      "last_duration_ms": 411,
      "delivered_at": null,
      "created_at": "2026-11-14T09:10:00.000Z"
    },
    {
      "id": "dlv_9496eae2-46fa-447d-bb3a-c18dc835a072",
      "event_id": "evt_58e9121f-e7ad-4371-804a-4b9eec3b53d3",
      "event_type": "order.placed",
      "status": "failed",
      "attempts": 8,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-14T09:50:00.000Z",
      "last_status_code": 500,
      "last_error": "the receiver answered HTTP 500",
      "last_duration_ms": 1832,
      "delivered_at": null,
      "created_at": "2026-11-14T09:00:00.000Z"
    }
  ]
}

Errors

StatusWhen
404No such webhook of yours.
422status or limit is not valid.

#Send a delivery again

POST/v1/webhooks/{id}/deliveries/{delivery_id}/redeliverwebhooks:write

Puts a delivery back in the queue (its attempts start again). Useful after you fixed a problem on your side.

Path parameters

NameTypeDescription
iduuidThe webhook's id.
delivery_idstringThe delivery's id (dlv_…).

Example

Queue again
curl -X POST "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9/deliveries/dlv_9496eae2-46fa-447d-bb3a-c18dc835a072/redeliver" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
202
{
  "status": "queued"
}

Errors

StatusWhen
404No such webhook or delivery of yours.
409The webhook is paused or switched off: set it to active first.