Webhooks | Everyn

Wie Everyn signierte Run-, Row-, Export- und Test-Events an Kundenendpunkte sendet.

Webhooks lassen Everyn dein System benachrichtigen, wenn Run-, Row-, Export- oder Test-Events auftreten. Endpoint-Konfiguration erfolgt über die API, Secrets werden von Everyn generiert, und Delivery Records bleiben inspizierbar, ohne Secret-Material offenzulegen.

Abonnierbare Event Types

eventTypes akzeptiert ausschließlich die folgenden Werte. Ein nicht unterstützter Wert wird beim Erstellen oder Aktualisieren des Endpoints abgelehnt — ein Tippfehler schlägt also sichtbar fehl, statt einen Endpoint zu erzeugen, der stillschweigend nie auslöst.

Event Type	Löst aus, wenn
`run.created`	Ein Run erstellt wird.
`run.succeeded`	Ein Run mit ausschließlich erfolgreichen Rows endet.
`run.completed_with_flags`	Ein Run endet, aber mindestens eine Row geflaggt ist.
`run.failed`	Ein Run in einem Failed State endet.
`run.canceled`	Ein Run abgebrochen wird.
`row.failed`	Eine einzelne Row fehlschlägt.
`export.ready`	Ein Export fertig und zum Download bereit ist.

webhook.test wird von der manuellen Test-Route geliefert und ist nicht abonnierbar, kann aber als Delivery-Filter genutzt werden. Alert Rules nutzen ein etwas breiteres Vokabular — siehe Alert Rules Reference. Der type-Filter auf GET /v1/runs/{runId}/events ist noch breiter: Er umfasst den vollständigen Run Event Stream, nicht nur die zustellbare Teilmenge.

Webhook Workflow

Webhook Endpoint erstellen:

curl -sS -X POST "$EVERYN_BASE_URL/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EVERYN_API_KEY" \
  -H "Idempotency-Key: webhook-001" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/everyn/webhooks",
    "eventTypes": ["run.succeeded", "row.failed", "export.ready"],
    "description": "Production webhook endpoint",
    "enabled": true
  }'

Signing Headers:

Everyn-Webhook-Id
Everyn-Webhook-Timestamp
Everyn-Webhook-Signature: v1=<lowercase hex hmac sha256>

Der signierte Inhalt ist:

<timestamp>.<raw UTF-8 body>

Webhook-Verhalten:

Thema	Vertrag
Secret-Sichtbarkeit	`signingSecret` wird nur bei Create oder `rotate-secret` zurückgegeben.
Payload-Form	Dünnes Event Envelope; sensible Details über authentifizierte API-Routen holen.
Endpoint URLs	Nur öffentliche HTTPS-URLs; unsichere lokale, credentialed, fragmentierte oder Non-Default-Port-URLs werden abgelehnt.
Delivery-Inspektion	`GET /v1/webhook-deliveries` und `GET /v1/webhook-deliveries/{deliveryId}` nutzen.
Manueller Test	`POST /v1/webhook-endpoints/{webhookEndpointId}/test` nutzen.
Secret Rotation	`POST /v1/webhook-endpoints/{webhookEndpointId}/rotate-secret` nutzen.

Nutze die generierte Webhooks-API-Referenz für Endpoint-Details und Authentifizierung für erforderliche Scopes.