Webhookit

Tämä opas kertoo, miten Shipitin lähtevät webhookit otetaan käyttöön, miten toimitukset varmennetaan ja mitä tapahtumia Shipit voi tällä hetkellä lähettää.

Mihin webhookeja käytetään

Lähtevien webhookien avulla Shipit kutsuu omaa päätepistettäsi aina, kun tuettu tapahtuma tapahtuu.

Tyypillisiä käyttötapoja:

• uusien lähetysten synkronointi omaan järjestelmään
• varausten epäonnistumisiin reagoiminen automaattisesti
• käyttöliittymän päivittäminen, kun uusi seurantatapahtuma saapuu
• lompakon hyvitysten, veloitusten ja alhaisen saldon hälytysten seuranta

Tuetut tapahtumat

Shipit tukee tällä hetkellä näitä lähteviä webhook-tapahtumia:

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

Esimerkkipayloadit löytyvät sivulta Tapahtumapayloadit ja seurantatilat.

Suositeltu käyttöönotto

1. Luo sovellukseesi HTTPS-päätepiste, joka hyväksyy JSON-dataa.
2. Palauta 2xx-vastaus, kun olet hyväksynyt payloadin.
3. Luo Shipitissä webhook ja lisää päätepisteesi URL.
4. Valitse tapahtumat, joihin haluat tilata ilmoitukset.
5. Kopioi allekirjoitussalaisuus ja tallenna se sovellukseesi.
6. Lähetä testiverkkohaku ja varmista, että päätepiste vastaanottaa sen.
7. Tarkista webhook-historiasta, että toimitus onnistui.

Pyyntömuoto

Shipit lähettää JSON-pyynnöt oletuksena näillä otsakkeilla:

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

Voit lisätä webhookin asetuksiin myös omia otsakkeita.

Allekirjoituksen varmistus

Shipit allekirjoittaa raaka-JSON-payloadin HMAC-SHA256-algoritmilla käyttäen webhookin allekirjoitussalaisuutta. Tuloksena syntyvä tiiviste lähetetään X-Webhook-Signature-otsakkeessa.

Suositeltu varmistus:

1. Lue raakapyynnön runko täsmälleen sellaisena kuin se vastaanotetaan.
2. Laske HMAC-SHA256 allekirjoitussalaisuudella.
3. Vertaa laskettua arvoa X-Webhook-Signature-otsakkeeseen vakioaikaisella vertailulla.
4. Hylkää pyyntö, jos allekirjoitukset eivät täsmää.

Toimituskäyttäytyminen

• Kaikki 2xx-vastaukset tulkitaan onnistuneiksi.
• Kaikki muut vastaukset tulkitaan epäonnistuneiksi.
• Myös verkko- ja aikakatkaisuvirheet tulkitaan epäonnistuneiksi.
• Epäonnistuneita toimituksia voidaan yrittää uudelleen webhookin retry-asetusten mukaisesti.
• Peräkkäiset epäonnistumiset voivat siirtää webhookin tarkistettavaksi.

HTTP-metodit ja tunnistautuminen

Shipit tukee näitä lähteviä HTTP-metodeja:

• GET
• POST
• PUT
• PATCH
• HEAD

POST on suositeltu oletus, ellei integraatiosi vaadi muuta.

Tunnistautumistavat:

• ei tunnistautumista
• Basic Auth
• Digest Auth

Aikakatkaisut, retryt ja payload-rajat

Jokaiselle webhookille voidaan määrittää:

• request timeout
• connection timeout
• retryjen enimmäismäärä
• retry-strategia
• retryn perusviive
• payloadin enimmäiskoko
• historiatietojen säilytysaika

Pyyntöhistoria

Shipit tallentaa jokaisen varsinaisen toimitusyrityksen webhook- historiaan, myös retryt. Jokaisesta yrityksestä näet:

• request URL:n ja HTTP-metodin
• otsakkeet
• payloadin
• vastauskoodin
• vastausrungon
• keston
• virheilmoituksen, jos vastausta ei saatu

Seurantatapahtumien tilat

shipment.tracking_event_updated sisältää kentän tracking_event.status, jonka arvo tulee Shipitin seurannan tila-enumista. Koko lista löytyy sivulta Tapahtumapayloadit ja seurantatilat.