Webhooks | Everyn

How Everyn sends signed run, row, export, and test events to customer endpoints.

Webhooks let Everyn notify your system when run, row, export, or test events happen. Endpoint configuration is API-managed, secrets are generated by Everyn, and delivery records stay inspectable without exposing secret material.

Subscribable event types

eventTypes accepts only the values below. An unsupported value is rejected when you create or update the endpoint, so a typo fails loudly instead of producing an endpoint that silently never fires.

Event type	Fires when
`run.created`	A run is created.
`run.succeeded`	A run finishes with every row successful.
`run.completed_with_flags`	A run finishes, but at least one row is flagged.
`run.failed`	A run finishes in a failed state.
`run.canceled`	A run is canceled.
`row.failed`	An individual row fails.
`export.ready`	An export finishes and is ready to download.

webhook.test is delivered by the manual test route and cannot be subscribed to, but you can filter deliveries by it. Alert rules use a different, slightly wider vocabulary — see the Alert rules reference. The type filter on GET /v1/runs/{runId}/events is wider still: it spans the full run event stream, not just the deliverable subset.

Webhook workflow

Create a webhook endpoint:

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>

The signed content is:

<timestamp>.<raw UTF-8 body>

Webhook behavior:

Topic	Contract
Secret visibility	`signingSecret` is returned only on create or `rotate-secret`.
Payload shape	Thin event envelope; fetch sensitive details through authenticated API routes.
Endpoint URLs	Public HTTPS URLs only; unsafe local, credentialed, fragmented, or non-default-port URLs are rejected.
Delivery inspection	Use `GET /v1/webhook-deliveries` and `GET /v1/webhook-deliveries/{deliveryId}`.
Manual test	Use `POST /v1/webhook-endpoints/{webhookEndpointId}/test`.
Secret rotation	Use `POST /v1/webhook-endpoints/{webhookEndpointId}/rotate-secret`.

Use the generated Webhooks API reference for endpoint details and Authentication for required scopes.