Veebikonksud

See juhend selgitab, kuidas seadistada Shipiti väljaminevaid veebikonksusid, kuidas tarneid kontrollida ja milliseid sündmusi Shipit praegu saata oskab.

Milleks veebikonksud on

Väljaminevad veebikonksud võimaldavad Shipitil kutsuda sinu endpointi iga kord, kui toimub toetatud sündmus.

Tüüpilised kasutused:

• uute saadetiste sünkroonimine oma süsteemi
• broneerimisvigadele automaatselt reageerimine
• kasutajaliidese uuendamine, kui saabub uus jälgimissündmus
• rahakoti krediteeringute, debiteeringute ja madala saldo hoiatuste jälgimine

Toetatud sündmused

Shipit toetab praegu järgmisi väljaminevaid webhook-sündmusi:

• shipment.booked
• shipment.failed
• shipment.tracking_event_updated
• pending_shipment.created
• pending_shipment.completed
• wallet.credited
• wallet.debited
• wallet.low_balance

Näidispayloadid leiad lehelt Sündmuste payloadid ja jälgimisolekud.

Soovitatud seadistus

1. Loo oma rakendusse HTTPS-endpoint, mis võtab vastu JSON-i.
2. Tagasta 2xx vastus kohe, kui oled payloadi vastu võtnud.
3. Loo Shipitis webhook ja lisa oma endpointi URL.
4. Vali sündmused, mida soovid tellida.
5. Kopeeri allkirjastamise saladus ja salvesta see oma rakendusse.
6. Saada test ja veendu, et sinu endpoint selle kätte saab.
7. Kontrolli Shipiti webhooki ajaloost, et kohaletoimetus õnnestus.

Päringu vorming

Shipit saadab JSON-päringuid järgmiste vaikimisi päistega:

• Content-Type: application/json
• X-Webhook-Signature: <hmac_sha256_signature>

Webhooki seadistuses saad lisada ka omaenda päiseid.

Allkirja kontroll

Shipit allkirjastab toore JSON-payloadi HMAC-SHA256 abil, kasutades webhooki allkirjastamise saladust. Saadud räsi saadetakse päises X-Webhook-Signature.

Soovitatud kontroll:

1. Loe päringu toorbody täpselt sellisel kujul, nagu see saabus.
2. Arvuta HMAC-SHA256, kasutades oma allkirjastamise saladust.
3. Võrdle arvutatud väärtust päisega X-Webhook-Signature, kasutades konstantse ajaga võrdlust.
4. Kui allkirjad ei ühti, lükka päring tagasi.

Kohaletoimetamise käitumine

• Iga 2xx vastus loetakse edukaks kohaletoimetuseks.
• Iga mitte-2xx vastus loetakse ebaõnnestumiseks.
• Ka võrgu- ja timeout-vead loetakse ebaõnnestumiseks.
• Ebaõnnestunud kohaletoimetusi saab webhooki retry-seadete järgi uuesti proovida.
• Järjestikused vead võivad viia webhooki ülevaatamist vajavasse olekusse.

HTTP-meetodid ja autentimine

Shipit toetab järgmisi väljaminevaid HTTP-meetodeid:

• GET
• POST
• PUT
• PATCH
• HEAD

POST on soovitatud vaikimisi valik, kui sinu integratsioon ei vaja midagi muud.

Toetatud autentimisviisid:

• autentimiseta
• Basic Auth
• Digest Auth

Timeoutid, retryd ja payloadi piirangud

Iga webhooki jaoks saab seadistada:

• request timeout
• connection timeout
• retryde maksimaalne arv
• retry-strateegia
• retry põhiline viivitus
• payloadi maksimaalne suurus
• ajaloo säilitamise aeg

Päringute ajalugu

Shipit salvestab webhooki ajalukku iga tegeliku kohaletoimetamise katse, sealhulgas retryd. Iga katse kohta näed:

• request URL-i ja HTTP-meetodit
• päiseid
• payloadi
• vastuse staatusekoodi
• vastuse bodyt
• kestust
• veateadet, kui vastust ei saadud

Jälgimissündmuste olekud

shipment.tracking_event_updated sisaldab välja tracking_event.status, mille väärtus tuleb Shipiti jälgimisolekute enumist. Täielik loend on lehel Sündmuste payloadid ja jälgimisolekud.