BoxLatviaIzstrādātājiem
Pieprasīt piekļuvi
API atsauce

Webhooks

Pārvaldiet adreses, ko BoxLatvia izsauc, kad kaut kas notiek. Kā notikumi izskatās, kā tos pārbaudīt un kā darbojas piegāde, ir aprakstīts Webhooks pamācībā.

#Webhook objekts

NosaukumsTipsApraksts
iduuidBoxLatvia webhook identifikators.
urlstringKur BoxLatvia sūta notikumus.
descriptionstring | nullJūsu piezīme, līdz 200 rakstzīmēm.
eventsstring[]Notikumi, ko saņemat: order.placed, order.cancelled, box.availability_changed.
statusstringactive (darbojas), paused (apturēts jūsu pusē) vai disabled (automātiski izslēgts pēc 30 neveiksmīgiem mēģinājumiem pēc kārtas). Iestatiet active, lai ieslēgtu atkal.
consecutive_failuresintegerNeveiksmīgi mēģinājumi pēc kārtas. Nonullējas pēc veiksmīga mēģinājuma.
disabled_reason disabled_atstring | null, datetime | nullKāpēc un kad tas tika izslēgts automātiski.
last_success_at last_failure_atdatetime | nullISO 8601, UTC.
created_at updated_atdatetimeISO 8601, UTC.

Izveidojot webhook, atbildē ir arī secret: parakstīšanas noslēpums, kas tiek parādīts tikai vienreiz.

#Piegādes objekts

NosaukumsTipsApraksts
idstringdlv_…. Tiek sūtīts arī jums kā galvene BoxLatvia-Delivery-Id.
event_idstringevt_…: notikuma satura id. Izmantojiet to, lai ignorētu dublikātus.
event_typestringorder.placed, order.cancelled, box.availability_changed vai webhook.test.
statusstringpending (gaida pirmo vai nākamo mēģinājumu), succeeded (izdevās), failed (atmests pēc 8 mēģinājumiem) vai cancelled (webhook apturēts vai izslēgts).
attemptsintegerVeiktie mēģinājumi.
next_attempt_atdatetime | nullKad paredzēts nākamais mēģinājums (tikai, kamēr gaida).
last_attempt_at delivered_at created_atdatetime | nullISO 8601, UTC.
last_status_codeinteger | nullHTTP statuss, ar kādu atbildēja jūsu adrese.
last_errorstring | nullKāpēc pēdējais mēģinājums neizdevās: īss teksts, nekad nevis jūsu atbilde.
last_duration_msinteger | nullCik ilgi ilga pēdējais mēģinājums.

#Galapunkti

#Pieteikties notikumiem

POST/v1/webhookswebhooks:write

Reģistrē adresi, ko BoxLatvia izsauc, kad notiek izvēlētie notikumi. Atbildē ir parakstīšanas noslēpums, kas tiek parādīts tikai vienreiz.

  • Saglabājiet secret tagad: tas vairs netiek parādīts (to var nomainīt). Ar to pārbauda katra notikuma parakstu.
  • Jums var būt ne vairāk kā 10 webhook. To pašu url nevar reģistrēt divreiz.
  • Atbilde, kas satur noslēpumu, nekad netiek atkārtota ar Idempotency-Key.

Vaicājuma parametri

NosaukumsTipsApraksts
validate_onlybooleantrue izpilda visas pārbaudes un parāda, kas notiktu, bet neko nesaglabā. Skatiet pārbaudi bez saglabāšanas.

Galvenes

NosaukumsTipsApraksts
Idempotency-KeystringNeobligāta. No 1 līdz 200 drukājamām rakstzīmēm. Atkārtots pieprasījums ar to pašu atslēgu atgriež sākotnējo rezultātu, nevis atkārto darbību. Skatiet drošu atkārtošanu.

Pieprasījuma saturs

NosaukumsTipsApraksts
url obligātsstringObligāts, veidojot. Tikai https, publisks resursdatora nosaukums (nevis IP adrese), ports 443 vai 8443, bez lietotājvārda un paroles.
events obligātsstring[]Obligāts, veidojot. Vismaz viens no order.placed, order.cancelled, box.availability_changed. Abi pasūtījumu notikumi satur nomnieka kontaktdatus, tāpēc tiem vajadzīgas arī tiesības orders:read.
descriptionstring | nullNeobligāta piezīme, līdz 200 rakstzīmēm.
statusstringTikai atjauninot: active vai paused.

Piemēri

Pieejamība un pasūtījumi
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"
}
Nederīgas vērtības
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"
    }
  ]
}
Pasūtījumu notikumiem vajadzīgs 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"
}
Viena un tā pati adrese divreiz
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"
}

Kļūdas

StatussKad
403Pasūtījumu notikums pieprasīts bez tiesībām orders:read.
409url jau ir reģistrēts (existing_id), vai jums jau ir 10 webhook (webhook-limit).
422Vērtība nav derīga: nav https, IP adrese vai iekšējs resursdatora nosaukums, nezināms notikums.

#Webhook saraksts

GET/v1/webhookswebhooks:read

Jūsu webhook.

Piemērs

Jūsu webhook
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"
    }
  ]
}

#Nolasīt webhook

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

Viens webhook. Noslēpums nekad netiek iekļauts.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Piemērs

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

Kļūdas

StatussKad
404Jums nav šāda webhook.

#Mainīt webhook

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

Maina adresi, notikumus, piezīmi vai statusu. Sūtiet tikai to, kas mainās.

Iestatiet status uz paused, lai uz laiku apturētu notikumus (gaidošie notikumi tiek atcelti), un uz active, lai sāktu atkal, arī pēc tam, kad BoxLatvia webhook izslēdza automātiski.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Vaicājuma parametri

NosaukumsTipsApraksts
validate_onlybooleantrue izpilda visas pārbaudes un parāda, kas notiktu, bet neko nesaglabā. Skatiet pārbaudi bez saglabāšanas.

Galvenes

NosaukumsTipsApraksts
Idempotency-KeystringNeobligāta. No 1 līdz 200 drukājamām rakstzīmēm. Atkārtots pieprasījums ar to pašu atslēgu atgriež sākotnējo rezultātu, nevis atkārto darbību. Skatiet drošu atkārtošanu.

Pieprasījuma saturs

NosaukumsTipsApraksts
url obligātsstringObligāts, veidojot. Tikai https, publisks resursdatora nosaukums (nevis IP adrese), ports 443 vai 8443, bez lietotājvārda un paroles.
events obligātsstring[]Obligāts, veidojot. Vismaz viens no order.placed, order.cancelled, box.availability_changed. Abi pasūtījumu notikumi satur nomnieka kontaktdatus, tāpēc tiem vajadzīgas arī tiesības orders:read.
descriptionstring | nullNeobligāta piezīme, līdz 200 rakstzīmēm.
statusstringTikai atjauninot: active vai paused.

Piemēri

Apturēt
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"
}
Mainīt notikumus
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"
}

Kļūdas

StatussKad
403Pasūtījumu notikums pieprasīts bez orders:read.
404Jums nav šāda webhook.
409Jaunais url jau ir reģistrēts.
422Vērtība nav derīga; status var būt tikai active vai paused.

#Dzēst webhook

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

Dzēš webhook un tā piegāžu vēsturi.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Vaicājuma parametri

NosaukumsTipsApraksts
validate_onlybooleantrue izpilda visas pārbaudes un parāda, kas notiktu, bet neko nesaglabā. Skatiet pārbaudi bez saglabāšanas.

Galvenes

NosaukumsTipsApraksts
Idempotency-KeystringNeobligāta. No 1 līdz 200 drukājamām rakstzīmēm. Atkārtots pieprasījums ar to pašu atslēgu atgriež sākotnējo rezultātu, nevis atkārto darbību. Skatiet drošu atkārtošanu.

Piemērs

Dzēšana
curl -X DELETE "$API/v1/webhooks/cb3cf942-3e09-4b76-9b89-0143c09a8ae9" \
  -u "$CLIENT_ID:$CLIENT_SECRET"
204 No Content
Atbildei nav satura

Kļūdas

StatussKad
404Jums nav šāda webhook.

#Nosūtīt testa notikumu

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

Nosūta notikumu webhook.test tikai uz šo adresi, parakstītu kā īstu. Tiek mēģināts vienreiz; rezultāts parādās piegādēs.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Piemērs

Testa ieplānošana
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."
}

Kļūdas

StatussKad
404Jums nav šāda webhook.

#Nomainīt noslēpumu

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

Izveido jaunu parakstīšanas noslēpumu. Vecais darbojas vēl 24 stundas: notikumi tiek parakstīti ar abiem, tāpēc varat pārslēgties, neizlaižot nevienu.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Vaicājuma parametri

NosaukumsTipsApraksts
validate_onlybooleantrue izpilda visas pārbaudes un parāda, kas notiktu, bet neko nesaglabā. Skatiet pārbaudi bez saglabāšanas.

Galvenes

NosaukumsTipsApraksts
Idempotency-KeystringNeobligāta. No 1 līdz 200 drukājamām rakstzīmēm. Atkārtots pieprasījums ar to pašu atslēgu atgriež sākotnējo rezultātu, nevis atkārto darbību. Skatiet drošu atkārtošanu.

Piemērs

Jauns noslēpums
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"
}

Kļūdas

StatussKad
404Jums nav šāda webhook.

#Piegāžu vēsture

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

Webhook jaunākās piegādes, jaunākās pirmās, ar pēdējā mēģinājuma rezultātu. Šeit var uzzināt, kāpēc notikumi nenonāk.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.

Vaicājuma parametri

NosaukumsTipsApraksts
statusstringpending, succeeded, failed vai cancelled.
limitintegerNo 1 līdz 100. Noklusējums ir 50.

Piemērs

Veiksmīga un neveiksmīga piegāde
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"
    }
  ]
}

Kļūdas

StatussKad
404Jums nav šāda webhook.
422status vai limit nav derīgs.

#Nosūtīt piegādi vēlreiz

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

Ieliek piegādi atpakaļ rindā (mēģinājumi sākas no jauna). Noder pēc tam, kad esat novērsis problēmu savā pusē.

Ceļa parametri

NosaukumsTipsApraksts
iduuidWebhook identifikators.
delivery_idstringPiegādes id (dlv_…).

Piemērs

Ieplānošana atkal
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"
}

Kļūdas

StatussKad
404Jums nav šāda webhook vai piegādes.
409Webhook ir apturēts vai izslēgts: vispirms iestatiet active.