info-icon


Webhook-udviklervejledning

Introduktion

FedEx Tracking Webhooks giver opdateringer om forsendelser næsten i realtid gennem hele forsendelsens livscyklus.

I modsætning til tracking-API'er, hvor applikationer skal anmode om forsendelsesstatus, leverer webhooks automatisk opdateringer om forsendelser, efterhånden som nye oplysninger bliver tilgængelige.

Denne vejledning omhandler:

  • Tre integrationsprincipper
  • Hvordan webhooks fungerer
  • Behandling af webhookdata
  • Kundenotifikationer
  • Tidsstempler
  • Bedste praksis og almindelige integrationsproblemer

Tre integrationsprincipper

Vellykkede webhookintegrationer følger tre principper.

Betragt alle webhookdata som en statusopdatering for en forsendelse

Antag ikke, at hvert datasæt repræsenterer en ny trackinghændelse. FedEx offentliggør nye data, hver gang nye oplysninger om forsendelsen bliver tilgængelige.

Data kan indeholde:

  • En ny trackinghændelse
  • Opdaterede leveringsprognoser
  • Oplysninger om kvittering
  • Modtageroplysninger
  • Andre ændringer i forsendelsesdata

Flere data kan dele samme trackinghændelse, samtidig med at de indeholder forskellige oplysninger om forsendelsen.

Gem og sammenflet forsendelsesdata

Hvert datasæt kan indeholde nye eller opdaterede oplysninger om forsendelsen. Gem dataene fra hver webhook, og sammenflet nye oplysninger med den eksisterende forsendelsespost.

Overskriv ikke den eksisterende forsendelsespost med de nyeste data. Bevar i stedet tidligere modtagne forsendelsesdata, og indarbejd nye oplysninger for at sikre en komplet og opdateret forsendelsespost gennem hele forsendelsens livscyklus.

Brug forretningsregler til at styre handlinger

Brug forretningsregler til at afgøre, hvornår systemer skal opdateres eller kunder skal underrettes.

Udløs ikke handlinger udelukkende ud fra en hændelseskode. Før kundevendte applikationer opdateres eller notifikationer sendes, skal følgende vurderes:

  • Trackinghændelser
  • Forsendelsestilgængelighed
  • Tidspunkt for afsendelse af notifikationer
  • Forretningskrav

Anbefalet behandlingsmodel

Følgende diagram illustrerer, hvordan de tre principper for webhookintegration fungerer sammen i en typisk implementering. Alle data fra en webhook behandles som en statusopdatering for en forsendelse, sammenflettes med en centraliseret forsendelsespost og evalueres i henhold til forretningsregler, før applikationer opdateres eller kundenotifikationer sendes.


Hvordan webhooks fungerer

FedEx offentliggør nye webhookdata, hver gang oplysninger om forsendelsen ændres eller bliver tilgængelige. En forsendelse kan generere flere data i løbet af sin livscyklus, herunder flere data, der er knyttet til samme trackinghændelse.

Yderligere data kan omfatte:

  • Trackinghændelser: Afhentet, I transit, Ude til levering og Leveret.
  • Forsendelsesdata: Kvittering (POD), Underskrevet kvittering (SPOD), GPS-kvittering (GPS POD) og modtageroplysninger.
  • Opdateringer af leveringsprognosen: Ændringer i forventet leveringsdato og -tidspunkt.
  • Leveringsundtagelser: Opdateringer og årsager til forsendelses- og leveringsundtagelser.
  • Opdateringer af forsendelsesmetadata: Adresseopdateringer, referencer og serviceoplysninger.
  • Driftsmæssige rettelser: Yderligere trackinghændelser og opdateringer af previousEvents.

Bemærk: Billede som leveringsbevis er ikke tilgængelig for alle leverede forsendelser. Tilgængeligheden afhænger af leveringstypen, krav om underskrift og andre forretningsregler.

Hvert datasæt repræsenterer forsendelsens senest kendte status. Behandl alle data for at sikre, at din forsendelsespost forbliver komplet og opdateret.

Sådan fungerer webhookopdateringer

Følgende eksempel viser, hvordan der kan genereres flere webhookdatasæt for den samme forsendelse i løbet af dens livscyklus. Nogle data introducerer en ny trackinghændelse. Andre tilføjer forsendelsesoplysninger såsom leveringsprognoser, kvitteringsdata eller forsendelsesoplysninger.

Vigtigt: Der kan genereres flere webhookdatasæt for samme trackinghændelse. Behandl alle data for at sikre, at nye forsendelsesoplysninger indarbejdes i forsendelsesposten.


Behandling af webhookdata

Behandl alle webhookdata som en statusopdatering for en forsendelse.

Antag ikke, at hvert webhookdatasæt repræsenterer en ny trackinghændelse. FedEx sender nye data, hver gang nye oplysninger om forsendelsen bliver tilgængelige. For eksempel kan en leveret forsendelse generere yderligere data, når oplysninger om kvittering, modtageroplysninger eller andre forsendelsesdata tilføjes eller opdateres.

For hvert datasæt skal du spørge:

  • Hvilken trackinghændelse er ændret?
  • Hvilke forsendelsesoplysninger er ændret?
  • Påvirker opdateringen en kundevendt applikation?
  • Udløser opdateringen en notifikation?

Behandl forsendelseshistorikken

Overvåg både scanEvent og previousEvents.

  • scanEvent indeholder den aktuelle trackinghændelse, der er knyttet til dataene.
  • previousEvents indeholder yderligere forsendelseshistorik, herunder hændelser, der muligvis ikke vises som den aktuelle scanEvent.

Nogle trackinghændelser vises i previousEvents i stedet for at blive offentliggjort som en ny scanEvent. Applikationer, der kun behandler scanEvent, kan gå glip af forsendelsesopdateringer og dermed generere ufuldstændige forsendelseshistorikker. Behandl begge datasamlinger for at få et fuldstændigt overblik over forsendelsen.

Vedligehold en forsendelsespost

Gem dataene fra hver webhook, og sammenflet nye oplysninger med den eksisterende forsendelsespost.

En komplet forsendelsespost giver indsigt næsten i realtid på tværs af:

  • Dashboards til tracking af forsendelser
  • Kundeserviceapplikationer
  • Ordrestyringssystemer (OMS)

Opdater forsendelsesposten med hvert datasæt for at opretholde det mest præcise og komplette overblik over forsendelsen.


Kundenotifikationer

Vælg en strategi for notifikationer ud fra din virksomheds behov og hvor mange oplysninger om forsendelsen, du ønsker at give.

FedEx Tracking Webhooks sender opdateringer om trackinghændelser og ændringer i forsendelsesdata næsten i realtid. Brug forretningsregler til at afgøre, hvilke opdateringer der er relevante for din virksomhed, og hvilke der kan ignoreres.

Almindelige strategier for notifikationer omfatter:

Notifikationer nær realtid

Send notifikationer umiddelbart efter, at en trackinghændelse indtræffer.

Fordele

  • Hurtigste kommunikation til kunderne
  • Laveste latenstid

Bemærk: Yderligere forsendelsesoplysninger er muligvis endnu ikke tilgængelige.

Udvidede notifikationer

Vent et par minutter efter en trackinghændelse, så yderligere oplysninger om forsendelsen kan nå frem.

For eksempel kan du efter en leveringshændelse vente et par minutter for at indhente følgende oplysninger:

  • Kvittering (POD)
  • Underskrift som leveringsbevis (Signature Proof of Delivery)
  • GPS-kvittering
  • Modtageroplysninger

Fordele

  • Mere komplette forsendelsesopdateringer til kunderne
  • Færre opfølgende notifikationer
  • Færre henvendelser til kundeservice

FedEx anbefaler at vente cirka fem minutter efter en leveringshændelse, fordi oplysninger om kvittering ofte tilføjes kort efter den første leveringshændelse.

Anbefalinger til tidspunkt for afsendelse af notifikationer

Tidspunktet for afsendelse af notifikationer varierer afhængigt af kunden og det konkrete anvendelsesformål. Men følgende anbefalinger bruges ofte til notifikationer til modtagere efter købet. For andre typer notifikationer (erhvervsbrugere, kundeservicemedarbejdere osv.) skal du vælge en strategi for notifikationer, der passer til dit anvendelsesformål.

  • Forventet levering: Vent cirka 15 minutter, efter at både forpligtet leveringsdato og første forventede leveringsdato (EDD) er tilgængelige.
  • Ude til levering: Send med det samme eller efter din virksomheds tidsplan (for eksempel dagligt kl. 08.00).
  • Leveret: Vent cirka 5 minutter, så de supplerende leveringsoplysninger kan nå frem.
  • Leveringsforsøg: Brug samme fremgangsmåde som for Leveret, så leveringsoplysningerne kan nå frem.

Opsætning af notifikationsregler baseret på virksomhedsdata

Ikke alle forsendelsesopdateringer kræver en notifikation. Definer notifikationsregler, der understøtter dine forretningskrav.

Anbefalet fremgangsmåde

Udløs ikke notifikationer udelukkende på baggrund af eventCode.

Vurder:

  • Trackinghændelse
  • Påkrævede forsendelsesdata
  • Forretningsregler

Generér kun notifikationer, når de nødvendige oplysninger er tilgængelige.

Denne fremgangsmåde hjælper med at forhindre:

  • Dublerede notifikationer
  • Manglende leveringsoplysninger
  • Ufuldstændige leveringsnotifikationer
  • Unødvendige opfølgningsnotifikationer

Tidsstempler

Brug det relevante tidsstempel til dit anvendelsesformål.

  • eventCreateTime: Da forsendelseshændelsen fandt sted. Brug det til kundevendt trackinghistorik.
  • Tidspunkt for afsendelse af notifikation: Tidspunktet, hvor FedEx sendte webhookdataene. Brug det kun til fejlfinding og overvågning, ikke til kundeoplevelser.

eventCreateTime afspejler, hvornår forsendelseshændelsen fandt sted. FedEx opdaterer ikke denne værdi, når der senere tilføjes yderligere forsendelsesoplysninger. For eksempel bevarer en leveringshændelse sit oprindelige eventCreateTime, selvom efterfølgende data indeholder yderligere oplysninger om kvittering eller andre opdateringer om forsendelsen. Som følge heraf bør eventCreateTime bruges til at identificere, hvornår hændelsen fandt sted, og ikke hvornår relaterede forsendelsesoplysninger blev tilføjet.

I nogle tilfælde er et hændelsestidspunkt muligvis ikke tilgængeligt. Når det sker, kan tidsstemplet indeholde en standardværdi på 00:00:00. Yderligere data kan indeholde et mere præcist tidsstempel, når det bliver tilgængeligt.


Bedste praksis og almindelige integrationsproblemer

Bedste praksis

  • Behandl dataene fra hver webhook – hver meddelelse kan indeholde en ny trackinghændelse eller en opdatering af forsendelsesdata.
  • Sammenflet trinvise opdateringer med din eksisterende forsendelsespost.
  • Overvåg både scanEvent og previousEvents for at indsamle hele forsendelsens historik.
  • Udløs kundenotifikationer ud fra forretningsregler, ikke kun rå hændelser.
  • Afsæt tid til forventede berigelser (f.eks. PPOD, SPOD, GPS), før kunderne underrettes.
  • Design en idempotent og robust behandling, der håndterer dubletter og meddelelser, der modtages i forkert rækkefølge.

Almindelige integrationsproblemer

  • At antager, at hvert datasæt repræsenterer en ny trackinghændelse.
  • At overskrive den eksisterende forsendelsespost med de nyeste data.
  • Udelukkende at basere sig på scanEvent.
  • At udløse notifikationer udelukkende på baggrund af eventCode.
  • At antage, at de første leverede data indeholder alle leveringsoplysninger.
  • At antage, at webhookmeddelelser kun ankommer én gang eller i kronologisk rækkefølge.

Oversigt

Behandl alle webhookdata som en statusopdatering for en forsendelse. Gem og sammenflet opdateringer om forsendelser, overvåg både scanEvent og previousEvents, og brug forretningsregler til at afgøre, hvornår applikationer skal opdateres, eller kunder skal underrettes.

Denne tilgang er med til at sikre et præcist overblik over forsendelser, en komplet trackinghistorik og mere velinformeret kommunikation med kunderne.