Webhooks

Den här guiden förklarar hur du konfigurerar Shipits utgående webhooks, verifierar leveranser och vilka händelser Shipit för närvarande kan skicka.

Vad webhooks används till

Utgående webhooks låter Shipit anropa din endpoint när en stödd händelse inträffar.

Vanliga användningsfall:

  • synka nybokade försändelser till ditt eget system
  • reagera automatiskt på bokningsfel
  • uppdatera ditt gränssnitt när en ny spårningshändelse kommer
  • övervaka plånbokskrediteringar, debiteringar och lågsaldovarningar

Händelser som stöds

Shipit stöder just nu följande utgående webhook-händelser:

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

Exempelpayloads finns på sidan Händelsepayloads och spårningsstatusar.

Rekommenderat upplägg

  1. Skapa en HTTPS-endpoint i din applikation som accepterar JSON.
  2. Returnera ett 2xx-svar när du har tagit emot payloaden.
  3. Skapa en webhook i Shipit och ange din endpoint-URL.
  4. Välj de händelser du vill prenumerera på.
  5. Kopiera signeringshemligheten och spara den i din applikation.
  6. Skicka ett test och verifiera att din endpoint tar emot det.
  7. Kontrollera webhook-historiken i Shipit för att bekräfta leveransen.

Requestformat

Shipit skickar JSON-förfrågningar med dessa standardheaders:

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

Du kan också lägga till egna headers i webhook-konfigurationen.

Signaturverifiering

Shipit signerar den råa JSON-payloaden med HMAC-SHA256 och webhookens signeringshemlighet. Den resulterande hashen skickas i headern X-Webhook-Signature.

Rekommenderat flöde:

  1. Läs rå request body exakt som den togs emot.
  2. Beräkna en HMAC-SHA256 med din signeringshemlighet.
  3. Jämför det beräknade värdet med X-Webhook-Signature med en konstanttidsjämförelse.
  4. Avvisa requesten om signaturerna inte matchar.

Leveransbeteende

  • Alla 2xx-svar behandlas som lyckade leveranser.
  • Alla andra svar behandlas som misslyckade leveranser.
  • Nätverksfel och timeouter behandlas också som misslyckanden.
  • Misslyckade leveranser kan försöka igen enligt webhookens retry-inställningar.
  • Upprepade fel kan flytta webhooken till ett granskningsläge.

HTTP-metoder och autentisering

Shipit stöder dessa utgående HTTP-metoder:

  • GET
  • POST
  • PUT
  • PATCH
  • HEAD

POST är det rekommenderade standardvalet om din integration inte kräver något annat.

Stödda autentiseringsmetoder:

  • ingen autentisering
  • Basic Auth
  • Digest Auth

Timeouter, retries och payloadgränser

Varje webhook kan konfigureras med:

  • request timeout
  • connection timeout
  • max antal retries
  • retry-strategi
  • grundfördröjning för retries
  • maximal payloadstorlek
  • lagringstid för historik

Requesthistorik

Shipit registrerar varje faktiskt leveransförsök i webhookhistoriken, inklusive retries. För varje försök kan du se:

  • request-URL och HTTP-metod
  • headers
  • payload
  • svarskod
  • svarsbody
  • varaktighet
  • felmeddelande om inget svar mottogs

Spårningsstatusar

shipment.tracking_event_updated innehåller ett tracking_event.status-värde från Shipits enum för spårningsstatus. Hela listan finns på sidan Händelsepayloads och spårningsstatusar.

Last Updated:
Contributors: Brian Faust