Ein Webhook sendet eine Nachricht an eine eigene Adresse, sobald in Ihrem Workspace etwas passiert, zum Beispiel wenn eine Bestellung bezahlt oder ein Abonnement gekündigt wird. So halten Sie ein anderes System auf dem gleichen Stand, etwa ein Tool wie Zapier, Ihre Buchhaltung oder Ihren eigenen Server.
Bevor Sie beginnen
Die Seite liegt unter Zahlungen > Einstellungen > Webhooks, in der Gruppe Entwickler. Zum Ansehen brauchen Sie Zahlungen ansehen. Um Endpunkte hinzuzufügen, zu ändern, zu testen und zu löschen, brauchen Sie Bestellungen / Kunden aktualisieren.
Einen Endpunkt hinzufügen
Klicken Sie auf den Button zum Hinzufügen, um Webhook-Endpunkt hinzufügen zu öffnen:
- Geben Sie unter Endpunkt einen optionalen Name und die Endpunkt-URL ein. Die Adresse muss aus dem Internet erreichbar sein. Adressen in einem privaten Netzwerk werden abgelehnt.
- Wählen Sie unter Events, was der Endpunkt empfangen soll. Events durchsuchen grenzt die Liste ein, das Kästchen einer Gruppe wählt die ganze Gruppe aus, und Alle auswählen oder Alle entfernen ändert alles auf einmal. Mindestens ein Event ist nötig.
- Klicken Sie auf Erstellen.
Die Events sind nach Themen gruppiert:
- Zahlungen: Bestellung bezahlt, Zahlung läuft, Zahlung fehlgeschlagen, Rechnung bezahlt, Rückerstattung erstellt.
- Abonnements: Abonnement erstellt, Abonnement verlängert, Abonnement gekündigt, Abo-Zahlung fehlgeschlagen.
- Mitglieder: Registrierungen, Anmeldungen, hinzugefügte oder entfernte Tags, geänderte Mitgliederfelder und neue Kontakte.
- Kurse & Events, Community und Daten & Postfach: abgeschlossene Kurse und Lektionen, Event-Anmeldungen und Teilnahmen, Beiträge, Level, Abzeichen, Postfach-Nachrichten und Tickets.
- Partner: neue Provisionen und ausgezahlte Auszahlungen, siehe die Hilfe zum Partnerprogramm.
Das Signing Secret
Direkt nachdem Sie den Endpunkt erstellt haben, zeigt der Workspace einmalig sein Signing Secret: Kopieren Sie jetzt Ihr Signing Secret. Speichern Sie es bei sich und klicken Sie dann auf Fertig. Es wird nicht noch einmal angezeigt.
Jede Zustellung wird als JSON mit dem Header X-Maio-Signature gesendet. Er enthält
einen HMAC-SHA256 des unveränderten Request-Bodys, erstellt mit Ihrem Secret, als
Hex-String in Kleinbuchstaben. Berechnen Sie denselben Wert bei sich und vergleichen Sie
ihn. So wissen Sie, dass die Nachricht aus Ihrem Workspace kommt. Die Header
X-Maio-Event und X-Maio-Delivery nennen das Event und die Zustellung.
Um das Secret zu ersetzen, öffnen Sie den Endpunkt und klicken auf Secret rotieren. Das alte Secret funktioniert sofort nicht mehr. Passen Sie Ihren Endpunkt deshalb umgehend an.
Testen
Öffnen Sie den Endpunkt und klicken Sie auf Test senden. Der Button wechselt zu Test in Warteschlange, und kurz darauf kommt ein Test-Event an Ihrem Endpunkt an. Es erscheint im Zustellprotokoll wie jede andere Zustellung.
Das Zustellprotokoll
Der Tab Zustellprotokoll listet jede Zustellung mit Ereignis, Endpunkt, Status, dem HTTP-Status, mit dem Ihr Endpunkt geantwortet hat, den Versuche und Wann. Filtern Sie nach Zugestellt, Fehlgeschlagen oder Offen. Der Bereich Zustellungen eines Endpunkts zeigt seine 20 letzten Zustellungen, bei jeder fehlgeschlagenen mit dem Fehler.
Eine Zustellung gilt als zugestellt, wenn Ihr Endpunkt innerhalb von 15 Sekunden mit einem 2xx-Status antwortet. Andernfalls wird sie nach 30 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden und 6 Stunden erneut versucht. Erneut senden sendet eine Zustellung mit demselben Inhalt noch einmal.
Nach 20 fehlgeschlagenen Versuchen in Folge für ein Event wird dieses Event für den Endpunkt ausgeschaltet. Antwortet der Endpunkt mit 410 Gone, wird das Event sofort ausgeschaltet. Beheben Sie das Problem am Endpunkt und schalten Sie ihn dann wieder auf Aktiv.
Ausschalten und löschen
Im Endpunkt wechselt der Schalter zwischen Aktiv und Deaktiviert. Ein deaktivierter Endpunkt empfängt nichts. Löschen entfernt ihn nach Ihrer Bestätigung mit allen seinen Events.
Über die API
Über die API verbundene Apps können eigene Endpunkte mit den /api/v1/hooks-Endpunkten
und einem API-Schlüssel mit dem Scope webhooks:manage einrichten. Sie erscheinen in
der Liste mit einem Badge API, und hier lassen sich nur ihr Name und ihr Status
ändern. Sie haben weder Secret rotieren noch Test senden. Siehe
API-Schlüssel und Entwicklerzugang.