Webhooks erstellen und verwalten

Pingen bietet für wichtige Ereignisse automatische Benachrichtigungen via Webhooks. So werden Sie beispielsweise in Echtzeit benachrichtigt, sobald ein Brief gesendet wurde, ein Problem aufweist oder unzustellbar ist. Dadurch können weitere Aktionen automatisch durchgeführt werden, ohne dass die Pingen API aktiv nach Veränderungen “gepollt” werden muss.

Webhook erstellen

Webhooks lassen sich direkt in der Pingen WebApp über den Menüpunkt «Organisation verwalten» --> «Webhooks» per Klick auf den Button «Ersten Webhook hinzufügen» erstellen.

Im nächsten Schritt muss die gewünschte Eventkategorie für den Webhook ausgewählt werden. Pingen bietet folgende Event-Kategorien:

• Brief-Probleme: Events, welche sich auf Probleme beim Versand eines Briefes beziehen. In der Regel geht es um Verarbeitungsprobleme wie zum Beispiel: PDF ist nicht im A4-Format, PDF hat Inhalte in den Sperrbereichen, zu wenig Guthaben verfügbar etc.
• Gesendete Briefe: Events, welche sich auf die Postzustellung beziehen, wie zum Beispiel: Ein Brief wurde an die Post übergeben oder eine postalische Tracking ID ist verfügbar.
• Unzustellbare Briefe: Events, welche sich auf Informationen beziehen, ob und weshalb Briefe von der Post als unzustellbar zurückgemeldet wurden.

Sobald eine Event-Kategorie ausgewählt wurde, muss die Webhook-URL (URL, an welche Pingen die Webhooks senden soll) sowie ein Signatur-Schlüssel angegeben werden. Bei der Webhook-URL ist es wichtig, dass diese auf dem Port 443 erreichbar ist. Der Signatur-Schlüssel wird verwendet, um sicherzustellen, dass nur Daten aus vertrauenswürdigen Quellen verarbeitet werden. Hierbei kann eine beliebige Zeichenfolge (mit max. 32 Zeichen) als Signatur-Schlüssel verwendet werden. Falls Sie einen Signatur-Schlüssel angeben, stellen Sie sicher, dass dieser Wert bei der Verarbeitung der Webhooks validiert wird.

Webhooks verwalten

Die Webhooks-Verwaltung lässt sich direkt in der Pingen WebApp über den Menüpunkt «Organisation verwalten» --> «Webhooks» per Klick auf den jeweiligen Webhook öffnen:

Die Webhooks-Verwaltung bietet eine Übersicht über sämtliche bisher versendeten Requests. Zudem lassen sich oben rechts jeweils Test-Requests versenden sowie sämtliche fehlgeschlagenen Requests erneut auslösen.

In der Übersicht wird neben den wichtigsten Informationen auch der jeweilige Status des Requests angezeigt. Requests können hierbei folgende Zustände haben:

• Erfolgreich: Webhook wurde erfolgreich zugestellt.
• Wird wiederholt: Webhook konnte bisher noch nicht erfolgreich zugestellt werden. Pingen wiederholt jedoch die Zustellung noch bis zu 7x.
• Fehlgeschlagen: Webhook konnte auch bei den Wiederholungen nicht erfolgreich zugestellt werden.

Per Klick auf einen Request lässt sich die Details-Ansicht vom jeweiligen Request öffnen:

In der Details-Ansicht sieht man sowohl den Inhalt des Requests sowie auch die jeweilige Rückmeldung von der Ziel-URL. Webhooks im Status «Fehlgeschlagen» lassen sich zudem über den Link in der Sidebar direkt erneut versenden.

Webhooks löschen

Webhooks lassen sich direkt in der Pingen WebApp über den Menüpunkt «Organisation verwalten» --> «Webhooks» löschen. Fahren Sie hierfür mit der Maus über den gewünschten Webhook und klicken Sie auf das Papierkorb-Icon: