Endpoint-Verifizierung

Die Verifizierung weist nach, dass die URL hinter einem Endpoint Ihnen gehört und für Webhooks bereit ist. Wir senden ihr eine signierte Challenge; sie besteht, indem sie die Challenge zurücksendet. Bis sie besteht, stellt ein Workspace, der Verifizierung verlangt, nichts an sie zu. Das fängt eine vertippte URL oder einen halb fertigen Empfänger ab, bevor sich echte Events in der Dead-Letter-Queue stapeln, und verhindert, dass jemand unsere Zustellungen auf einen Server richtet, der nie darum gebeten hat.

Die Challenge

Wenn Sie eine Verifizierung starten, wird ein POST an die URL des Endpoints gesendet, signiert mit dem Secret des Endpoints, genau wie eine Zustellung (dieselben X-Webhook-Signature und X-Webhook-Timestamp, die Custom-Header Ihres Endpoints und X-Webhook-Event-Type: webhook.verify):

JSON

{"type": "webhook.verify", "data": {"endpoint_id": "ep_3f9a…", "challenge": "Xb9kQ2…"}}

Der Endpoint besteht, wenn er mit 2xx antwortet und den Wert von challenge irgendwo im Response-Body enthält. Ein 2xx ohne das Token schlägt mit challenge_not_echoed fehl; alles andere schlägt fehl wie bei einer Zustellung.

Die Challenge beantworten

Prüfen Sie die Signatur wie bei jeder Zustellung und geben Sie dann die Challenge zurück:

event = json.loads(raw_body)                       # after the signature check
if event["type"] == "webhook.verify":
    return Response(event["data"]["challenge"], status=200)

No REST example here; showing Python.

Verifizierung ausführen

Öffnen Sie in der Konsole auf der Seite Endpoints das Menü des Endpoints und wählen Sie Verify. Über die API:

Shell

curl -sX POST https://webhooks.nimbusnexus.net/v1/endpoints/ep_3f9a…/verify \
  -H "Authorization: Bearer $ADMIN_KEY"

JSON

{ "verified": true, "challenge_echoed": true, "status_code": 200, "error": null, "duration_ms": 142, "failure_reason": null }

Ein Endpoint bleibt verifiziert, bis sich seine URL ändert; eine neue URL muss erneut verifiziert werden.

Wann sie verlangt wird

Die Verifizierung wird für einen Endpoint verlangt, wenn eine der folgenden Vorgaben aktiv ist:

der Schalter für den Workspace — Settings → Endpoint verification in der Konsole oder PATCH /v1/workspace mit {"require_endpoint_verification": true};
der Schalter für das Projekt — PUT /v1/verification-policy?project_id=… mit {"required": true}, für ein Projekt, das sie braucht, während andere sie nicht brauchen;
Ihr Tarif, sofern er sie verlangt. Die Konsole zeigt den Schalter dann als fest eingeschaltet.

GET /v1/verification-policy liefert die Regel, wie die Zustellung sie anwendet (required), zusammen mit den beiden Schaltern.

Was einem nicht verifizierten Endpoint entgeht

Wenn die Verifizierung verlangt wird, wird ein nicht verifizierter Endpoint bei der Verteilung eines Events ausgelassen: Die Antwort auf den Publish zählt ihn in skipped_unverified, die Konsole markiert den Endpoint als gated, und für ihn wird keine Zustellung erstellt — es wartet also nichts darauf, gesendet zu werden, sobald er verifiziert ist. Veröffentlichen Sie das Event erneut oder spielen Sie es erneut ab, nachdem der Endpoint bestanden hat.

Erneutes Senden wird ebenso zurückgehalten. Eine einzelne Zustellung erneut an diesen Endpoint zuzustellen oder ein Event erneut an ihn abzuspielen, wird mit 409 endpoint_not_verified abgewiesen; eine Sammel-Neuzustellung oder ein Replay über einen Zeitraum lässt ihn aus und zählt ihn in skipped_unverified. Eine Zustellung, die bereits in der Warteschlange steht oder wiederholt wird, wenn der Endpoint eine Verifizierung braucht — weil die Anforderung eingeschaltet wurde oder sich die URL des Endpoints geändert hat —, geht ungesendet in die Dead-Letter-Queue, mit einem last_error, das mit „not verified:“ beginnt. Verifizieren Sie den Endpoint und stellen Sie die Zustellung dann erneut zu.

Empfänger, die nicht antworten können

Manche Empfänger nehmen jeden POST an, geben aber nie einen Body Ihrer Wahl zurück — darunter die Incoming Webhooks von Slack und die Catch Hooks von Zapier. Sie können die Verifizierung nicht bestehen. Wo Ihr Tarif es zulässt, lassen Sie die Verifizierung für das Projekt ausgeschaltet, das an sie zustellt; andernfalls schalten Sie ein kleines eigenes Relay davor, das die Challenge beantwortet.

Nächste Schritte

Signaturprüfung — die Prüfung, die Sie vor dem Beantworten der Challenge ausführen.
Zustellungen und Retries — was geschieht, sobald der Endpoint Events empfängt.
Schnellstart — von null zur verifizierten Zustellung.