Webhooks

Denne guiden forklarer hvordan du setter opp Shipits utgående webhooks, hvordan du verifiserer leveranser, og hvilke hendelser Shipit kan sende i dag.

Hva webhooks brukes til

Utgående webhooks lar Shipit kalle endpointet ditt når en støttet hendelse skjer.

Vanlige bruksområder:

  • synkronisere nye bookede sendinger til ditt eget system
  • reagere automatisk på bookingfeil
  • oppdatere grensesnittet ditt når en ny sporingshendelse kommer
  • overvåke wallet-krediteringer, debiteringer og varsler om lav saldo

Støttede hendelser

Shipit støtter for tiden disse utgående webhook-hendelsene:

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

Eksempelpayloads finnes på siden Hendelsespayloads og sporingsstatuser.

Anbefalt oppsett

  1. Opprett et HTTPS-endpoint i applikasjonen din som godtar JSON.
  2. Returner en 2xx-respons når du har akseptert payloaden.
  3. Opprett en webhook i Shipit og legg inn endpoint-URL-en din.
  4. Velg hendelsene du vil abonnere på.
  5. Kopier signeringshemmeligheten og lagre den i applikasjonen din.
  6. Send en test og bekreft at endpointet ditt mottar den.
  7. Gå gjennom webhook-historikken i Shipit for å bekrefte leveringen.

Request-format

Shipit sender JSON-requests med disse standardheaderne:

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

Du kan også legge til egne headere i webhook-konfigurasjonen.

Signaturverifisering

Shipit signerer den rå JSON-payloaden med HMAC-SHA256 ved hjelp av webhookens signeringshemmelighet. Den resulterende hashen sendes i headeren X-Webhook-Signature.

Anbefalt flyt:

  1. Les rå request body nøyaktig slik den ble mottatt.
  2. Beregn en HMAC-SHA256 med signeringshemmeligheten din.
  3. Sammenlign den beregnede verdien med X-Webhook-Signature ved hjelp av en konstanttids-sammenligning.
  4. Avvis requesten hvis signaturene ikke stemmer.

Leveringsatferd

  • Alle 2xx-responser behandles som vellykkede leveranser.
  • Alle ikke-2xx-responser behandles som feil.
  • Nettverksfeil og timeouts behandles også som feil.
  • Feilede leveranser kan forsøkes på nytt etter webhookens retry-innstillinger.
  • Gjentatte feil kan flytte en webhook til en tilstand som krever review.

HTTP-metoder og autentisering

Shipit støtter disse utgående HTTP-metodene:

  • GET
  • POST
  • PUT
  • PATCH
  • HEAD

POST er det anbefalte standardvalget med mindre integrasjonen din krever noe annet.

Støttede autentiseringsmetoder:

  • ingen autentisering
  • Basic Auth
  • Digest Auth

Timeouts, retries og payloadgrenser

Hver webhook kan konfigureres med:

  • request timeout
  • connection timeout
  • maksimalt antall retries
  • retry-strategi
  • grunnforsinkelse for retry
  • maksimal payloadstørrelse
  • lagringstid for historikk

Requesthistorikk

Shipit registrerer hvert faktisk leveringsforsøk i webhook-historikken, inkludert retries. For hvert forsøk kan du se:

  • request-URL og HTTP-metode
  • headere
  • payload
  • responsstatuskode
  • responsbody
  • varighet
  • feilmelding hvis det ikke kom noen respons

Sporingsstatuser

shipment.tracking_event_updated inneholder en tracking_event.status-verdi fra Shipits enum for sporingsstatuser. Hele listen finnes på siden Hendelsespayloads og sporingsstatuser.

Last Updated:
Contributors: Brian Faust