Die Webhook-URL setzen oder ihr Secret rotieren
- In der Sandbox
In einfachen Worten
Der Schlüssel des Betreibers setzt den Webhook des Betreibers, der die Ereignisse aller Kunden erhält; der Admin-Schlüssel eines Kunden setzt
den eigenen Webhook dieses Kunden, der nur dessen Ereignisse erhält. Der erste Aufruf braucht url und erzeugt das Secret, das einmal zurückgegeben wird. Beim Rotieren wird das neue Secret
einmal zurückgegeben. 24 Stunden lang signiert der Service jede Zustellung mit dem neuen und dem alten Secret, damit der Partner
umstellen kann, ohne Ereignisse zu verlieren. Zugestellt werden nur Ereignisse, die nach dem ersten Aufruf geschrieben wurden.
Die URL muss https sein, und jede Adresse, auf die ihr Host auflöst, muss öffentlich sein: Loopback-, private, Link-Local-, Carrier-Grade-NAT-, Multicast-, reservierte und Cloud-Metadaten-Adressen werden abgelehnt, hier und erneut vor jeder Zustellung. Weiterleitungen werden nicht verfolgt.
Seit 0.16.0 wird jeder Query-Parameter mit 400 beantwortet, sodass ein falsch geschriebenes client nie den Webhook des Betreibers ändern kann.
apiKeyAuthorizationBearer <token>Senden Sie Ihren Schlüssel als Bearer-Token: Authorization: Bearer <your-api-key>. Der Systemzustand ist der einzige Aufruf, der keinen Schlüssel braucht.
application/json- body
url?string^https://uriactive?booleanrotate_secret?booleanfalsecontact_email?|length <= 254Gespeichert.
application/json- response
url*|^https://uriactive*booleansecret_rotated_at?|date-timecontact_email?|Wen man informiert, wenn Zustellungen aufgegeben werden.
last_delivery?|nullsecret?stringNur vorhanden, wenn in diesem Aufruf ein Secret erzeugt oder rotiert wurde.
curl -X PUT "https://example.com/webhook" \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -d '{}'{ "url": "http://example.com", "active": true, "secret_rotated_at": "2019-08-24T14:15:22Z", "contact_email": "string", "last_delivery": { "at": "2019-08-24T14:15:22Z", "http_status": 0 }, "secret": "string"}Die Webhook-Einstellungen abrufen (die des Betreibers, oder mit dem Admin-Schlüssel eines Kunden dessen eigene) GET
Seit 0.16.0 liest der Schlüssel des Betreibers mit client die Einstellungen eines Kunden. Der Admin-Schlüssel eines Kunden darf nur seinen eigenen Kunden nennen; jeder andere wird mit 404 beantwortet. Ein unbekannter oder wiederholter Parameter oder ein leerer client wird mit 400 beantwortet. Das Setzen und Testen eines Webhooks nimmt gar keine Query-Parameter an (400): Es bleibt beim eigenen Schlüssel des Webhooks.
Ein signiertes Testereignis an die Webhook-URL senden POST
Der Body enthält event_id, type (immer test), occurred_at und message, signiert wie ein Statusereignis. Er meldet keine Rechnung. Seit 0.16.0 wird jeder Query-Parameter mit 400 beantwortet.