Webhooks

HMAC-signed run.completed / run.failed notifications — register endpoints, verify signatures, and inspect the delivery log.

Last updated August 23, 2026

Webhooks are the recommended integration shape: register an endpoint once and Wavemaker calls you when a run finishes, instead of you polling GET /runs/{id}. Deliveries fire after terminal settle — run.completed when a run succeeds, run.failed when it fails — so by the time your handler runs, billing has settled and outputs are final.

Webhook management uses your session JWT (sign in), not an API key. See API & MCP for auth basics.

Register an endpoint

POST /webhooks
{ "url": "https://example.com/hooks/wavemaker", "events": ["run.completed", "run.failed"] }

The 201 response includes the signing secret exactly once. Store it — GET /webhooks lists your endpoints but never returns secrets again. If you lose it, rotate:

POST /webhooks/{endpointId}/rotate-secret   → new secret, again returned exactly once
DELETE /webhooks/{endpointId}               → remove the endpoint

Verify deliveries

Each delivery is a JSON POST with three headers:

  • X-Webhook-Signature: v1=<hex> — HMAC-SHA256 of the raw request body using your secret
  • X-Webhook-ID — unique event id (<runId>:<event>)
  • X-Webhook-Timestamp — Unix seconds, for replay checks

Recompute the HMAC over the raw body and compare it to the signature before trusting the payload. The body carries event, id, run_id, workflow_id, status, created_at, and completed_at — fetch full details with GET /runs/{run_id} from your handler.

Delivery is at-least-once: settle replays can re-send the same event, so deduplicate on id (or X-Webhook-ID).

Retries and dead-lettering

A delivery that does not get a 2xx response is retried up to 5 attempts with backoff (1 min, 5 min, 30 min, 2 h). After the fifth failure it moves to dead letter and stops retrying automatically.

Inspect and recover from the delivery log:

GET /webhooks/deliveries?limit=50            → newest first: status, attempt count, response code, last error
POST /webhooks/deliveries/{deliveryId}/retry → re-send a failed or dead-lettered delivery now

Already-delivered receipts cannot be retried (409). The same log backs the developer dashboard, so you can debug an integration without shell access to your server.

Test an endpoint

POST /webhooks/{endpointId}/test

Sends a webhook.test event signed with the endpoint’s real stored secret and the same headers as production deliveries — use it to validate your signature check end-to-end before wiring real runs.