---
title: Webhooks
description: Configure HTTPS endpoints in the Developer console to receive signed run lifecycle events.
source: https://www.edgaze.ai/docs/api/webhooks
section: api
---
# Webhooks

> Configure HTTPS endpoints in the Developer console to receive signed run lifecycle events.

Configure HTTPS endpoints in the Developer console to receive signed run lifecycle events. Webhooks complement polling: use them when you need push notification instead of a poll loop.

## Subscribable events

- `run.completed`: dispatched when a run succeeds.
- `run.failed`: dispatched when a run fails.
- `run.started`: configurable at creation but not currently dispatched. Subscribe for forward compatibility.

## Verification

Each delivery includes `edgaze-signature: t=<unix>,v1=<hmac>` and `edgaze-webhook-id`. The signed payload is `{timestamp}.{raw_json_body}` using HMAC-SHA256 with your endpoint secret. Reject signatures older than five minutes to prevent replay.

## Delivery guarantees

- Five-second HTTP timeout per delivery attempt.
- Webhook failures never block run completion: your handler must be idempotent.
- Use test delivery and delivery logs in the Developer console to debug signature or payload issues.
- Return 2xx quickly; defer heavy processing to a background worker using the run id in the payload.

## Payload reference

```json
{
  "type": "run.completed",
  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "success",
  "runUrl": "https://api.edgaze.ai/v1/runs/7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "occurredAt": "2026-07-08T10:00:42.000Z"
}
```