Das Zustellprotokoll des Webhooks
- In der Sandbox
Seit 0.28.0. Die Zustellungen eines Webhooks, der neueste Versuch zuerst (ohne Versuch zuletzt), mit Status, Fehlern und Zeiten jeder Zustellung, aber nicht das Ereignis selbst. Ein Kundenschlüssel mit dem Scope read liest den Webhook des eigenen Kunden (ein anderer Kunde wird mit 404 beantwortet); der Schlüssel des Betreibers liest den eigenen Webhook des Betreibers oder mit client den eines Kunden; der schreibgeschützte Betreiberschlüssel liest dasselbe. Höchstens limit Zeilen (Standard 100, höchstens 500), mit truncated, wenn es mehr gibt.
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.
client?string^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$state?string"pending""delivered""dead"limit?integer1 <= value <= 500100Die Zustellungen.
application/json- response
data*array<>truncated*booleancurl -X GET "https://example.com/webhook/deliveries" \ -H "Authorization: Bearer <your-api-key>"{ "data": [ { "invoice_id": "string", "sequence": 0, "event_id": "string", "state": "pending", "failures": 0, "first_failure_at": "2019-08-24T14:15:22Z", "last_attempt_at": "2019-08-24T14:15:22Z" } ], "truncated": true}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.
Die Webhook-URL setzen oder ihr Secret rotieren PUT
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.