Webhooks

Denne guide forklarer, hvordan du sætter Shipits udgående webhooks op, hvordan du verificerer leveringer, og hvilke hændelser Shipit i øjeblikket kan sende.

Hvad webhooks bruges til

Udgående webhooks gør det muligt for Shipit at kalde dit endpoint, når en understøttet hændelse sker.

Typiske anvendelser:

  • synkronisere nybookede forsendelser til dit eget system
  • reagere automatisk på bookingfejl
  • opdatere dit interface, når en ny sporingshændelse ankommer
  • overvåge wallet-krediteringer, debiteringer og lav saldo-advarsler

Understøttede hændelser

Shipit understøtter i øjeblikket disse udgå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

Eksempelpayloads findes på siden Hændelsespayloads og sporingsstatusser.

Anbefalet opsætning

  1. Opret et HTTPS-endpoint i din applikation, som accepterer JSON.
  2. Returnér et 2xx-svar, når du har accepteret payloaden.
  3. Opret en webhook i Shipit og tilføj dit endpoint-URL.
  4. Vælg de hændelser, du vil abonnere på.
  5. Kopiér signeringshemmeligheden og gem den i din applikation.
  6. Send en test og bekræft, at dit endpoint modtager den.
  7. Gennemgå webhook-historikken i Shipit for at bekræfte leveringen.

Request-format

Shipit sender JSON-requests med disse standardheaders:

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

Du kan også tilføje dine egne headers i webhook-konfigurationen.

Signaturverifikation

Shipit signerer den rå JSON-payload med HMAC-SHA256 ved hjælp af webhookens signeringshemmelighed. Den resulterende hash sendes i headeren X-Webhook-Signature.

Anbefalet flow:

  1. Læs request body råt og præcist som modtaget.
  2. Beregn en HMAC-SHA256 med din signeringshemmelighed.
  3. Sammenlign den beregnede værdi med X-Webhook-Signature med en constant-time sammenligning.
  4. Afvis requesten, hvis signaturerne ikke matcher.

Leveringsadfærd

  • Alle 2xx-svar behandles som succesfulde leveringer.
  • Alle ikke-2xx-svar behandles som fejl.
  • Netværksfejl og timeouts behandles også som fejl.
  • Fejlede leveringer kan prøves igen efter webhookens retry-indstillinger.
  • Gentagne fejl kan flytte en webhook til en tilstand, der kræver review.

HTTP-metoder og autentificering

Shipit understøtter disse udgående HTTP-metoder:

  • GET
  • POST
  • PUT
  • PATCH
  • HEAD

POST er det anbefalede standardvalg, medmindre din integration kræver noget andet.

Understøttede autentificeringsmetoder:

  • ingen autentificering
  • Basic Auth
  • Digest Auth

Timeouts, retries og payloadgrænser

Hver webhook kan konfigureres med:

  • request timeout
  • connection timeout
  • maksimalt antal retries
  • retry-strategi
  • grundlæggende retry-forsinkelse
  • maksimal payloadstørrelse
  • opbevaringsperiode for historik

Requesthistorik

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

  • request-URL og HTTP-metode
  • headers
  • payload
  • svarstatuskode
  • svarbody
  • varighed
  • fejlmeddelelse, hvis der ikke blev modtaget et svar

Sporingsstatusser

shipment.tracking_event_updated indeholder værdien tracking_event.status fra Shipits enum for sporingsstatusser. Den fulde liste findes på siden Hændelsespayloads og sporingsstatusser.

Last Updated:
Contributors: Brian Faust