Kunden-Webhooks konfigurieren
Registrieren Sie einen HTTPS-Empfänger für unterstützte Ereignisse, schützen Sie den Signaturschlüssel und untersuchen Sie Fehler anhand des Zustellverlaufs.
- Empfänger vorbereitenVerwenden Sie einen öffentlichen HTTPS-Endpunkt, der JSON annimmt.
- Ereignisse abonnierenGeben Sie Name, URL und Ereignistypen des Endpunkts an.
- Signatur schützenSpeichern Sie das einmalige Geheimnis und prüfen Sie eingehende Anfragen.
- Zustellungen prüfenBeheben Sie Fehler anhand von Status und Antwortdaten.
- Endpunkt pflegenRotieren Sie Geheimnisse oder widerrufen Sie nicht mehr benötigte Ziele.
Unterstützte Kundenereignisse
Das Kundenformular bietet die Ereignisse „Auftrag abgeschlossen“, „Rechnung ausgestellt“ und „Kontingentschwelle erreicht“. Wählen Sie nur Ereignisse, die Ihr Empfänger verarbeitet. Endpunkte gehören zu Ihrem persönlichen oder ausgewählten Organisationskontext. Eigentümer und Administratoren der Organisation können sie verwalten; Mitglieder können sie ansehen, aber nicht ändern. Webhooks senden Benachrichtigungen und ändern weder Bestellung noch Rechnung.
- Öffnen Sie Webhooks im vorgesehenen Organisationskontext.
- Wählen Sie mindestens ein Ereignis, das Ihr Empfänger verarbeitet.
- Verwenden Sie für getrennte Umgebungen unterschiedliche Endpunkte.
Öffentliches Ziel registrieren
Erstellen Sie einen Endpunkt mit einem Namen von 2 bis 120 Zeichen, einer gültigen URL und mindestens einem aufgeführten Ereignis. Erforderlich sind HTTPS und ein öffentlicher Hostname. Lokale, interne und private IP-Ziele werden abgewiesen; eine lokale Entwicklungs-URL funktioniert daher nicht. Senden Sie das Formular erst ab, wenn der Empfänger JSON annehmen und eine erfolgreiche HTTP-Antwort liefern kann.
- Betreiben Sie den Empfänger unter einer stabilen öffentlichen HTTPS-Adresse.
- Geben Sie URL, aussagekräftigen Namen und Ereignisauswahl ein.
- Senden Sie einmal ab und korrigieren Sie angezeigte Validierungsfehler.
Signierte Nachrichten prüfen
Beim Erstellen wird ein Signaturschlüssel einmalig angezeigt. Anfragen enthalten Header für Ereignis, Zustellung, Zeitstempel und HMAC-Signatur sowie JSON mit Ereignis-ID, Typ, Erstellungszeit und Daten. Prüfen Sie die Signatur über Zeitstempel und unveränderten Rohdatenkörper, begrenzen Sie das zulässige Zeitfenster und verarbeiten Sie doppelte IDs idempotent. Protokollieren Sie das Geheimnis nicht und senden Sie es nicht an den Support.
- Speichern Sie das Geheimnis in der geschützten Empfängerkonfiguration.
- Prüfen Sie die Signatur anhand des unveränderten Request-Bodys.
- Speichern Sie Ereignis-IDs, damit doppelte Aktionen ausbleiben.
Zustellverlauf lesen
Die Seite zeigt die letzten 50 Zustellungen über alle Ihre Endpunkte. Erfolgreiche HTTP-Antworten erhalten den Status „erfolgreich“. Serverfehler und Ratenbegrenzungen können erneut versucht werden; andere erfolglose Antworten können sofort fehlschlagen. Nach Erreichen der Wiederholungsgrenze enden weitere Versuche. Der Verlauf enthält Antwortstatus und einen begrenzten Antworttext oder Fehler. Ein Ereignis erscheint nicht, wenn es nicht eingetreten ist oder der Endpunkt es nicht abonniert hat.
- Prüfen Sie Ereignis, Versuchszahl, Status und letzten Fehler.
- Beheben Sie Verfügbarkeit, Antwortverhalten oder Ratenbegrenzung des Empfängers.
- Kontrollieren Sie eine spätere Zustellung auf den Status „erfolgreich“.
Signaturschlüssel rotieren
Durch die Rotation wird das Endpunktgeheimnis ersetzt und der Endpunkt reaktiviert. Empfänger, die nur den alten Wert verwenden, weisen neue Anfragen ab. Bereiten Sie die sichere Aktualisierung der Empfängerkonfiguration vor, rotieren Sie beim vorgesehenen Endpunkt, übernehmen Sie den neuen Wert und verteilen Sie ihn umgehend. Bei Offenlegung rotieren Sie sofort und prüfen den Zustellverlauf auf unerwartete Aktivität.
- Ermitteln Sie die Empfängerinstanzen und bereiten Sie die sichere Verteilung vor.
- Rotieren Sie den Endpunkt und speichern Sie das einmalig angezeigte Geheimnis.
- Prüfen Sie, ob die nächste erwartete Zustellung erfolgreich ist.
Endpunkte ersetzen oder widerrufen
Kunden können Endpunkte erstellen, Geheimnisse rotieren und Endpunkte widerrufen. URL und Ereignisauswahl lassen sich nicht bearbeiten. Für eine Änderung erstellen Sie einen Ersatz, prüfen dessen Zustellungen und widerrufen anschließend den alten Endpunkt. Der Widerruf stoppt künftige Zustellungen und setzt den Status auf inaktiv. Nutzen Sie das auch bei stillgelegten Zielen oder offengelegten Geheimnissen und prüfen Sie danach die Liste.
- Erstellen Sie einen Ersatz mit korrigierter URL oder Ereignisauswahl.
- Prüfen Sie, ob der Ersatz Ereignisse erfolgreich empfängt.
- Widerrufen Sie den alten Endpunkt und kontrollieren Sie seinen Status.
Häufig gestellte Fragen
Welche Ereignisse kann ich abonnieren?
Auftrag abgeschlossen, Rechnung ausgestellt und Kontingentschwelle erreicht.
Kann ich HTTP ohne TLS verwenden?
Nein. Erforderlich ist eine öffentliche HTTPS-URL.
Kann ich das Geheimnis erneut ansehen?
Nein. Rotieren Sie den Endpunkt, um ein neues Geheimnis zu erhalten.
Warum ist eine Zustellung noch ausstehend?
Ein vorübergehender Serverfehler oder eine Ratenbegrenzung kann einen erneuten Versuch auslösen.
Warum ist die Zustellung fehlgeschlagen?
Prüfen Sie Antwort und Wiederholungsverlauf auf die Ursache.
Kann ich einen Endpunkt bearbeiten?
Nein. Ersetzen und prüfen Sie ihn und widerrufen Sie den alten Endpunkt.