Webhook-Entwicklerhandbuch
Einleitung
FedEx Tracking Webhooks liefern Sendungsaktualisierungen nahezu in Echtzeit während des gesamten Versandzyklus der Sendung.
Im Gegensatz zu Sendungsverfolgungs-APIs, bei denen Anwendungen den Sendungsstatus anfordern müssen, liefern Webhooks Sendungsaktualisierungen automatisch, sobald neue Informationen verfügbar sind.
Dieses Handbuch behandelt:
- Drei Integrationsprinzipien
- Wie Webhooks funktionieren
- Webhook-Payloads verarbeiten
- Kundenbenachrichtigungen
- Zeitstempel
- Bewährte Vorgehensweisen und häufige Integrationsprobleme
Drei Integrationsprinzipien
Erfolgreiche Webhook-Integrationen folgen drei Prinzipien.
Verarbeiten Sie jede Webhook-Payload als Aktualisierung des Sendungsstatus
Gehen Sie nicht davon aus, dass jede Payload einen neuen Meilenstein der Sendungsverfolgung darstellt. FedEx veröffentlicht eine neue Payload, sobald neue Informationen zur Sendung verfügbar werden.
Eine Payload kann Folgendes enthalten:
- Ein neues Sendungsverfolgungsereignis
- Aktualisierte Zustellvorhersagen
- Informationen zum Zustellnachweis
- Empfängerinformationen
- Weitere Änderungen an Sendungsdaten
Mehrere Payloads können denselben Meilenstein der Sendungsverfolgung aufweisen und dabei unterschiedliche Informationen zur Sendung enthalten.
Sendungsdaten speichern und zusammenführen
Jede Payload kann neue oder aktualisierte Informationen zur Sendung enthalten. Speichern Sie jede Webhook-Payload und führen Sie neue Informationen mit dem bestehenden Sendungsdatensatz zusammen.
Überschreiben Sie den bestehenden Sendungsdatensatz nicht mit der neuesten Payload. Bewahren Sie stattdessen die zuvor empfangenen Sendungsdaten auf und integrieren Sie neue Informationen, damit während des gesamten Versandzyklus der Sendung ein vollständiger und aktueller Sendungsdatensatz erhalten bleibt.
Steuern Sie Aktionen mithilfe von Geschäftsregeln
Verwenden Sie Geschäftsregeln, um zu bestimmen, wann Systeme aktualisiert oder Kund*innen benachrichtigt werden sollen.
Lösen Sie Aktionen nicht allein aufgrund eines Ereigniscodes aus. Bevor Sie kundenorientierte Anwendungen aktualisieren oder Benachrichtigungen senden, prüfen Sie:
- Meilensteine der Sendungsverfolgung
- Verfügbarkeit der Sendung
- Zeitpunkt der Benachrichtigung
- Geschäftsanforderungen
Empfohlenes Verarbeitungsmodell
Das folgende Diagramm veranschaulicht, wie die drei Prinzipien der Webhook-Integration bei einer typischen Implementierung zusammenwirken. Jede Webhook-Payload wird als Aktualisierung des Sendungsstatus verarbeitet, in einen zentralen Sendungsdatensatz integriert und anhand von Geschäftsregeln ausgewertet, bevor Anwendungen aktualisiert oder Kund*innen benachrichtigt werden.
Wie Webhooks funktionieren
FedEx veröffentlicht eine neue Webhook-Payload, sobald sich Informationen zur Sendung ändern oder verfügbar werden. Eine Sendung kann im Laufe ihres Versandzyklus mehrere Payloads generieren, einschließlich mehrerer Payloads, die demselben Meilenstein der Sendungsverfolgung zugeordnet sind.
Zusätzliche Payloads können Folgendes enthalten:
- Meilensteine der Sendungsverfolgung: Abgeholt, unterwegs, in Zustellung und zugestellt.
- Sendungsdaten: Zustellnachweis (PPOD), Unterschriftsnachweis (SPOD), GPS-Zustellnachweis (GPS POD) und Empfängerinformationen.
- Aktualisierungen zu Zustellprognosen: Änderungen des voraussichtlichen Zustelldatums und der voraussichtlichen Zustellzeit.
- Zustellausnahmen: Aktualisierungen und Gründe zu Sendungs- und Zustellausnahmen.
- Aktualisierungen der Sendungsmetadaten: Adressaktualisierungen, Referenzen und Servicedetails.
- Operative Korrekturen: Zusätzliche Meilensteine der Sendungsverfolgung und Aktualisierungen von
previousEvents.
Hinweis: Ein Zustellnachweis per Foto ist nicht für alle zugestellten Sendungen verfügbar. Die Verfügbarkeit hängt von der Zustellart, den Unterschriftsanforderungen und anderen Geschäftsregeln ab.
Jede Payload stellt den zuletzt bekannten Status der Sendung dar. Verarbeiten Sie jede Payload, um sicherzustellen, dass Ihr Sendungsdatensatz vollständig und aktuell bleibt.
Webhook-Aktualisierungen verstehen
Das folgende Beispiel zeigt, wie im Verlauf des Versandzyklus einer Sendung mehrere Webhook-Payloads generiert werden können. Einige Payloads führen einen neuen Meilenstein der Sendungsverfolgung ein. Andere fügen Sendungsinformationen hinzu, z. B. Zustellprognosen, Zustellnachweisdaten oder Sendungsdetails.
Wichtig: Für denselben Sendungsverfolgungsmeilenstein können mehrere Webhook-Payloads generiert werden. Verarbeiten Sie jede Payload, um sicherzustellen, dass neue Sendungsinformationen in den Sendungsdatensatz übernommen werden.
Webhook-Payloads verarbeiten
Verarbeiten Sie jede Webhook-Payload als Aktualisierung des Sendungsstatus.
Gehen Sie nicht davon aus, dass jede Payload einen neuen Meilenstein der Sendungsverfolgung darstellt. FedEx veröffentlicht eine neue Payload, sobald neue Informationen zur Sendung verfügbar werden. Beispielsweise kann eine zugestellte Sendung zusätzliche Payloads generieren, wenn Informationen zum Zustellnachweis, Empfängerinformationen oder andere Sendungsdaten hinzugefügt oder aktualisiert werden.
Fragen Sie für jede Payload:
- Welcher Meilenstein der Sendungsverfolgung hat sich geändert?
- Welche Sendungsinformationen wurden geändert?
- Betrifft das Update eine kundenorientierte Anwendung?
- Löst die Aktualisierung eine Benachrichtigung aus?
Verarbeiten Sie den Sendungsverlauf
Überwachen Sie sowohl scanEvent als auch previousEvents.
scanEvententhält den aktuellen Meilenstein der Sendungsverfolgung, der der Payload zugeordnet ist.previousEventsenthält zusätzliche Informationen zum Sendungsverlauf, einschließlich Meilensteinen, die möglicherweise nicht als aktuellesscanEventangezeigt werden.
Einige Meilensteine der Sendungsverfolgung erscheinen in previousEvents, anstatt als neues scanEvent veröffentlicht zu werden. Anwendungen, die nur scanEvent verarbeiten, können Sendungsaktualisierungen übersehen und unvollständige Sendungsverläufe erzeugen. Verarbeiten Sie beide Abholungen, um ein vollständiges Bild der Sendung zu erhalten.
Pflegen Sie einen Sendungsdatensatz
Speichern Sie jede Webhook-Payload und führen Sie neue Informationen mit dem bestehenden Sendungsdatensatz zusammen.
Ein vollständiger Sendungsdatensatz bietet nahezu in Echtzeit Einblick in:
- Sendungsverfolgungs-Dashboards
- Kundendienstanwendungen
- Auftragsabwicklungssysteme (OMS)
Aktualisieren Sie den Sendungsdatensatz mit jeder Payload, um die genaueste und vollständigste Übersicht über die Sendung zu gewährleisten.
Kundenbenachrichtigungen
Wählen Sie eine Benachrichtigungsstrategie basierend auf Ihren Geschäftsanforderungen und dem Detailgrad der Sendungsinformationen, den Sie bereitstellen möchten.
FedEx Tracking Webhooks senden nahezu in Echtzeit Aktualisierungen zu Meilensteinen der Sendungsverfolgung und Änderungen an Sendungsdaten. Verwenden Sie Geschäftsregeln, um zu bestimmen, welche Aktualisierungen für Ihr Unternehmen relevant sind und welche ignoriert werden können.
Zu den gängigen Benachrichtigungsstrategien zählen:
Benachrichtigungen in nahezu Echtzeit
Senden Sie Benachrichtigungen unmittelbar nach Eintritt eines Meilensteins der Sendungsverfolgung.
Vorteile
- Schnellste Kundenkommunikation
- Niedrigste Latenz
Hinweis: Zusätzliche Informationen zur Sendung sind möglicherweise noch nicht verfügbar.
Erweiterte Benachrichtigungen
Warten Sie nach einem Meilenstein der Sendungsverfolgung einige Minuten, damit zusätzliche Sendungsinformationen eintreffen können.
Warten Sie beispielsweise nach einem Meilenstein zur erfolgten Zustellung einige Minuten, um Folgendes zu erfassen:
- Zustellnachweis (POD)
- Unterschriftsnachweis (SPOD)
- GPS-Zustellnachweis
- Empfängerinformationen
Vorteile
- Umfassendere Sendungsaktualisierungen für Kund*innen
- Weniger Folgebenachrichtigungen
- Weniger Kontakte mit dem Kundendienst
FedEx empfiehlt, nach dem Meilenstein zur erfolgten Zustellung etwa fünf Minuten zu warten, da Informationen zum Zustellnachweis häufig kurz nach dem ersten Zustellereignis hinzugefügt werden.
Empfehlungen zum Timing von Benachrichtigungen
Der Zeitpunkt der Benachrichtigung variiert je nach Kund*in und Anwendungsfall. Die folgenden Empfehlungen werden jedoch üblicherweise für Empfängerbenachrichtigungen nach dem Kauf verwendet. Wählen Sie für andere Benachrichtigungsarten (Geschäftsbenutzer*in, Kundendienstmitarbeiter*in usw.) eine Benachrichtigungsstrategie, die zu Ihrem Anwendungsfall passt.
- Voraussichtliche Zustellung: Warten Sie etwa 15 Minuten, nachdem sowohl das Zusage-Datum als auch das erste voraussichtliche Zustelldatum (EDD) verfügbar sind.
- In Zustellung: Senden Sie sofort oder gemäß Ihrem Geschäftszeitplan (zum Beispiel täglich um 8:00 Uhr).
- Zugestellt: Warten Sie etwa 5 Minuten, damit zusätzliche Zustellinformationen eingehen können.
- Zustellversuch: Wenden Sie denselben Ansatz wie bei „Zugestellt“ an, damit Zustellinformationen eingehen können.
Benachrichtigungsregeln auf Grundlage von Geschäftsdaten erstellen
Nicht jede Sendungsaktualisierung erfordert eine Benachrichtigung. Definieren Sie Benachrichtigungsregeln, die Ihre Geschäftsanforderungen erfüllen.
Empfohlener Ansatz
Lösen Sie Benachrichtigungen nicht ausschließlich auf Grundlage von eventCode aus.
Prüfen Sie:
- Meilensteine der Sendungsverfolgung
- Erforderliche Sendungsdaten
- Geschäftsregeln
Erstellen Sie Benachrichtigungen nur, wenn die erforderlichen Informationen verfügbar sind.
Dieser Ansatz hilft, Folgendes zu verhindern:
- Doppelte Benachrichtigungen
- Fehlende Zustellinformationen
- Unvollständige Zustellbenachrichtigungen
- Unnötige Folgebenachrichtigungen
Zeitstempel
Verwenden Sie je nach Anwendungsfall den passenden Zeitstempel.
eventCreateTime: Zeitpunkt, zu dem das Sendungsereignis aufgetreten ist. Verwenden Sie es für den kundenorientierten Verlauf der Sendungsverfolgung.- Zeitpunkt des Nachrichtenversands: Zu dem Zeitpunkt, an dem FedEx die Webhook-Payload gesendet hat. Verwenden Sie es nur zur Fehlerbehebung und Überwachung, nicht für kundenorientierte Nutzererlebnisse.
eventCreateTime gibt an, wann das Sendungsereignis stattgefunden hat. FedEx aktualisiert diesen Wert nicht, wenn später zusätzliche Sendungsinformationen hinzugefügt werden. Beispielsweise behält ein Zustellereignis seine ursprüngliche eventCreateTime bei, selbst wenn nachfolgende Payloads Informationen zum Zustellnachweis oder andere Aktualisierungen der Sendung hinzufügen. Daher sollte eventCreateTime verwendet werden, um zu ermitteln, wann das Ereignis stattgefunden hat, und nicht, wann zugehörige Sendungsinformationen hinzugefügt wurden.
In einigen Fällen ist möglicherweise keine Ereigniszeit verfügbar. Wenn dies geschieht, kann der Zeitstempel den Standardwert 00:00:00 enthalten. Zusätzliche Payloads können einen genaueren Zeitstempel enthalten, sobald dieser verfügbar ist.
Bewährte Vorgehensweisen und häufige Integrationsprobleme
Best Practices
- Verarbeiten Sie jede Webhook-Payload – jede Nachricht kann ein neues Sendungsverfolgungsereignis oder eine Aktualisierung von Sendungsdaten enthalten.
- Führen Sie inkrementelle Aktualisierungen mit Ihrem bestehenden Sendungsdatensatz zusammen.
- Überwachen Sie sowohl
scanEventals auchpreviousEvents, um den vollständigen Sendungsverlauf zu erfassen. - Lösen Sie Kundenbenachrichtigungen anhand von Geschäftsregeln aus, nicht nur auf Basis unverarbeiteter Ereignisse.
- Planen Sie Zeit für erwartete Datenanreicherungen (z. B. PPOD, SPOD, GPS) ein, bevor Sie Kund*innen benachrichtigen.
- Konzipieren Sie eine idempotente, fehlertolerante Verarbeitung, die doppelte und in falscher Reihenfolge eintreffende Nachrichten handhabt.
Häufige Integrationsprobleme
- Sie gehen davon aus, dass jede Payload einen neuen Meilenstein der Sendungsverfolgung darstellt.
- Sie überschreiben den Sendungsdatensatz mit der neuesten Payload.
- Sie verlassen sich ausschließlich auf
scanEvent. - Sie lösen Benachrichtigungen ausschließlich auf Grundlage von
eventCodeaus. - Sie gehen davon aus, dass die zuerst zugestellte Payload alle Zustelldetails enthält.
- Sie gehen davon aus, dass Webhook-Nachrichten nur einmal oder in chronologischer Reihenfolge eintreffen.
Übersicht
Verarbeiten Sie jede Webhook-Payload als Aktualisierung des Sendungsstatus. Speichern Sie Sendungsaktualisierungen und führen Sie sie zusammen, überwachen Sie sowohl scanEvent als auch previousEvents und verwenden Sie Geschäftsregeln, um zu bestimmen, wann Anwendungen aktualisiert oder Kund*innen benachrichtigt werden sollen.
Dieser Ansatz trägt dazu bei, eine präzise Sendungstransparenz, einen vollständigen Verlauf der Sendungsverfolgung und eine besser informierte Kundenkommunikation zu gewährleisten.
