Webhooks - Efflux

What a webhook is

A webhook is a saved HTTPS endpoint. Reference it from any callback with callback_id set to the webhook id (whook_...). Efflux signs the body so you can reject anything that did not come from your key.

POST/v3/webhooks

Create a webhook

API reference

Request fields

Field	Required	Notes
`name`	yes	Label in your webhook list
`url`	yes	Endpoint that will receive deliveries
`description`	no
`method`	no	HTTP method Efflux will use
`headers`	no	Extra headers added to each delivery
`verify_tls`	no	Verify the endpoint certificate. Defaults on when omitted

Create returns 201 with the webhook and a secret. The secret is shown once. Later reads return secret_hint only. Rotate when you need a new secret. The response of rotate includes the new secret once.

curl -sS -X POST "https://api.efflux.io/v3/webhooks" \
  -H "Authorization: Bearer $EFFLUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Scan sink",
    "url": "https://example.com/efflux",
    "method": "POST",
    "verify_tls": true
  }'

Verify the signature

Each delivery sets:

Header	Value
`Efflux-Event`	Event name
`Efflux-Delivery-Id`	Delivery id
`Efflux-Webhook-Id`	Webhook id
`Efflux-Signature`	`t=<unix>,v1=<hex>`

v1 is HMAC-SHA256, keyed with the webhook secret, over the ASCII string <unix>. concatenated with the raw body. Compare in constant time, and reject timestamps outside the window you allow.

Do not put Efflux-Event, Efflux-Delivery-Id, Efflux-Webhook-Id, or Efflux-Signature in the headers map. Those names are reserved.

Manage and test

GET/v3/webhooks

List webhooks

API reference

GET/v3/webhooks/{webhook_id}

Get a webhook

API reference

PUT/v3/webhooks/{webhook_id}

Replace mutable fields

API reference

DELETE/v3/webhooks/{webhook_id}

Delete a webhook

API reference

POST/v3/webhooks/{webhook_id}/rotate-secret

Rotate the signing secret

API reference

POST/v3/webhooks/{webhook_id}/test

Send a test delivery

API reference

GET/v3/webhooks/{webhook_id}/deliveries

Delivery history

API reference

Update can change name, description, url, method, headers, active, and verify_tls. It does not change the secret. The list defaults to limit 20 (max 200).

Use the webhook id as callback.success.callback_id (or start / fail) on a job. You can also save that id on preferences so new jobs pick it up when the request leaves the phase empty.

Deleting or deactivating a webhook does not edit preferences or schedules.

Where the id is set	What happens
On the job request	Create is rejected
Only in preferences	That phase is skipped. The job is still created. `GET /preferences` reports `issues`
On a schedule's stored request	That run is not created. The schedule keeps the id

The app lists webhooks under Settings then Preferences. Create, update, and delete still use these routes.