Was sind Webhooks und wie richtet man sie in Sendcloud ein? – Sendcloud Help Center

Zweck: Erfahre die Grundlagen über Webhooks und wie du sie in deinem Sendcloud-Panel konfigurieren kannst.

Um Webhooks nutzen zu können, musst du dich über eine API mit Sendcloud verbinden. Für weitere Informationen zur Verbindung mit unserer API verweisen wir dich auf unsere API-Dokumentation.

Weitere Informationen zu Sendcloud-Webhooks findest du in den Abschnitten über Webhooks in unserer API-Dokumentation.

Für integrationsspezifische Webhook-Unterstützung schau dir unseren Artikel an: Verbesserung der Webhook-Sicherheit und Integrationsunterstützung. Er erklärt die Einrichtung von Webhooks für verschiedene Integrationen und gibt dir bewährte Methoden, um deine Webhooks zu sichern.

Was sind Webhooks?

Webhooks ermöglichen es Anwendungen, in "Echtzeit" miteinander zu kommunizieren. Eine andere Möglichkeit für Anwendungen, miteinander zu kommunizieren, ist über eine API. Im Gegensatz zu einer API, die mit Polling arbeitet, empfängt ein Webhook Daten, sobald die Anwendung sie verarbeitet. Es muss keine Anfrage gestellt werden, da es sich um einen automatischen Prozess handelt. Daher musst du dir keine Sorgen über eine Verzögerung bei der Kommunikation machen.

API: Eine API holt sich regelmäßig Daten aus der Anwendung, indem sie eine Anfrage stellt.

Webhook: Ein Webhook zieht keine Daten, sondern bekommt Daten von der Anwendung gepusht, sobald sie entstehen.

Beispiel: Empfang von Tracking-Updates von Sendcloud

(Siehe Bilder unten als Referenz)

Wenn du ein Tracking-Update über die API erhältst, läuft es wie folgt ab:
Deine Anwendung versucht, Tracking-Daten von Sendcloud über ein Intervall zu beziehen. Das tut sie auch, wenn keine neuen Daten verfügbar sind.
Wenn du Tracking-Updates über einen Webhook erhalten möchtest, geht das wie folgt:
Sendcloud schickt die Tracking-Updates an deine Anwendung, sobald sie in Sendcloud verfügbar sind.

Sendcloud Webhooks

Webhook Integration Object: Dieser Webhook kommt ins Spiel, wenn eine neue API-Integration zu Sendcloud hinzugefügt wird. Er wird ausgelöst, wenn eine API-Integration verbunden, gelöscht oder aktualisiert wird. Klicke hier, um zu sehen, was in der Nutzlast dieses Webhooks enthalten ist.

Webhook Object „Paketstatus geändert“: Dieser Webhook wird aktiviert, wenn sich der Status eines Pakets ändert, unabhängig davon, wie sich der Status ändert. Klicke hier, um zu sehen, was in der Nutzlast dieses Webhooks enthalten ist.

Webhook Return Created Object: Dieser Webhook wird ausgelöst, wenn eine Rücksendung über die API oder das Retourenportal erstellt wird. Klicke hier, um die Details der Payload zu sehen.

Wie richte ich Webhooks in Sendcloud ein?

Damit Sendcloud aktiv Paketaktualisierungen (z. B. Tracking-Updates) übermittelt, musst du einen API-Endpunkt erstellen. Jedes Mal, wenn eine Aktualisierung stattfindet, stellt Sendcloud eine Anfrage über diesen Endpunkt. Weitere Informationen findest du im Abschnitt Webhooks in unserer API-Dokumentation.

Kopiere die Webhook-URL aus deiner Anwendung in deine Zwischenablage
Gehe zu deinem Sendcloud-Panel und öffne deine Integrationseinstellungen, indem du zu Einstellungen > Integrationen > Konfigurieren gehst.
Aktiviere das Kästchen bei Webhook-Feedback aktiviert
Suche das Feld Webhook-URL (siehe Abbildung unten) und füge die Webhook-URL dort ein
Teste deinen Webhook, indem du auf die Schaltfläche Test API webhook Button klickst.
Klicke auf Speichern

Geschafft! Dein Webhook ist nun eingerichtet und die Daten sollten nun in deiner Anwendung ankommen. Du kannst dies nutzen, um Trigger einzurichten, die zu bestimmten Aktionen führen. Ein Beispiel wäre, dass du deine Tracking-E-Mails mit den eingehenden Tracking-Updates verbindest. Auf diese Weise kannst du deinen Kunden sofortige Updates zukommen lassen.

Für Retourenpakete erhältst du nur dann Webhook-Updates, wenn die ausgehende Sendung über den API Shop erstellt wurde.

FAQ

Wenn ich einen Webhook einrichte, für welche Pakete gilt er?

Webhooks werden pro Integration konfiguriert. Das bedeutet, dass der Webhook nur für Pakete gilt, die über die Integration erstellt wurden, für die der Webhook eingerichtet wurde. Pakete, die über andere Integrationen oder Methoden erstellt wurden, lösen diesen Webhook nicht aus.

Warum gibt meine Webhook-URL eine 404 zurück oder ist nicht erreichbar?

Problem: Die Webhook-URL ist falsch (z. B. Tippfehler, falsche Domain oder fehlendes HTTPS) oder der Endpunkt ist nicht öffentlich erreichbar.

Beispiele:

404 Not Found

DNS resolution failed

Lösung: Überprüfe die URL-Syntax und die Domain sorgfältig. Stelle sicher, dass der Endpunkt öffentlich erreichbar ist und HTTPS mit einem gültigen SSL/TLS-Zertifikat verwendet.

Warum erhalte ich SSL/TLS-Zertifikatsfehler bei meinem Webhook?

Problem: Der Endpunkt verwendet ein abgelaufenes, selbstsigniertes oder falsch konfiguriertes Zertifikat.

Beispiele:

SSL Handshake failed

Unable to verify certificate

Lösung: Installiere ein gültiges SSL-Zertifikat von einer vertrauenswürdigen Zertifizierungsstelle (CA), erneuere abgelaufene Zertifikate und überprüfe, ob Zwischenzertifikate korrekt installiert sind.

Warum laufen Webhook-Anfragen ab oder antworten nicht?

Problem: Der Server, der den Webhook empfängt, reagiert zu langsam oder gar nicht.

Beispiele:

 Request timed out

 Connection reset

Lösung: Stelle sicher, dass der Server innerhalb des Zeitlimits antwortet, optimiere den Code für eine schnellere Verarbeitung oder verschiebe rechenintensive Aufgaben in Hintergrundprozesse. Überprüfe außerdem Firewalls oder mögliche Rate-Limits.

Warum gibt mein Webhook HTTP-Fehler wie 405 oder 500 zurück?

Problem: Der Endpunkt erwartet eine bestimmte HTTP-Methode oder liefert keine korrekten Antworten zurück.

Beispiele:

405 Method Not Allowed

500 Internal Server Error

Lösung: Stelle sicher, dass der Endpunkt POST-Anfragen akzeptiert, bei erfolgreichem Empfang einen Statuscode aus dem 2xx-Bereich zurückgibt und Fehler ordnungsgemäß protokolliert bzw. behandelt werden.

Warum schlägt die Authentifizierung oder Signaturprüfung meines Webhooks fehl?

Problem: Der Webhook-Anbieter signiert Anfragen, aber der Endpunkt überprüft sie nicht korrekt oder verwendet falsche Schlüssel.

Beispiele:

401 Unauthorized

403 Forbidden

Lösung: Implementiere eine HMAC- oder Signaturprüfung mit dem richtigen geheimen Schlüssel und stelle sicher, dass Header und Payload genau so verarbeitet werden, wie sie gesendet wurden.

Warum ist die Payload meines Webhooks ungültig oder fehlerhaft formatiert?

Problem: Der Webhook sendet Daten im JSON- oder einem anderen Format, aber der Empfänger kann sie nicht korrekt verarbeiten.

Beispiele:

400 Bad Request

Unexpected token in logs

Lösung: Überprüfe, ob der Content-Type unterstützt wird (meist application/json), validiere und protokolliere die Payload und aktualisiere den Code des Endpunkts, um neue Felder oder Formate zu unterstützen.

Warum werden einige Webhook-Anfragen rate-begrenzt oder verworfen?

Problem: Der Endpunkt wird überlastet und beginnt, Anfragen zu verwerfen.

Beispiele:

429 Too Many Requests

Requests delayed or silently failing

Lösung: Implementiere eine Warteschlange oder ein Throttling, um Lastspitzen zu bewältigen, richte Wiederholungsversuche (Retries) mit exponentiellem Backoff ein und überwache bzw. skaliere die Serverressourcen bei Bedarf.

Klicke hier, um zu unserer Sendcloud-API-Referenz zu gelangen und die Payload des Webhooks zu sehen.