> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adskull.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive completion events instead of polling every job.

Webhooks are recommended for production automations. Polling is simpler for the first integration, but webhooks reduce wait time and request volume.

## Events

| Event            | Trigger                                                             |
| ---------------- | ------------------------------------------------------------------- |
| `job.completed`  | A generation job completed successfully.                            |
| `job.failed`     | A generation job failed and any refundable credits were reconciled. |
| `job.queued`     | A generation job was accepted for processing.                       |
| `voice.cloned`   | A custom cloned voice was created.                                  |
| `voice.designed` | A custom designed voice was created.                                |

## Payload

```json theme={"theme":"github-dark"}
{
  "id": "0d4edb98-9af7-4a5d-9320-0bfe7a1c3f9b",
  "type": "job.completed",
  "created_at": "2026-05-17T12:05:00Z",
  "object": "event",
  "job": {
    "id": "vid_01HX...",
    "type": "video_generation",
    "status": "completed",
    "credits_reserved": 80,
    "credits_used": 80,
    "credits_refunded": 0,
    "output_urls": ["https://cdn.adskull.io/generated/video.mp4"],
    "created_at": "2026-05-17T12:00:00Z",
    "updated_at": "2026-05-17T12:05:00Z",
    "completed_at": "2026-05-17T12:05:00Z",
    "failed_at": null,
    "failure_code": null,
    "failure_message": null
  }
}
```

## Security

Each delivery includes these headers:

| Header                | Value                                       |
| --------------------- | ------------------------------------------- |
| `X-AdSkull-Event`     | Event type, such as `job.completed`.        |
| `X-AdSkull-Delivery`  | Unique delivery event ID.                   |
| `X-AdSkull-Timestamp` | Unix timestamp used in the signature.       |
| `X-AdSkull-Signature` | `t=<timestamp>,v1=<hmac_sha256>` signature. |

Verify the signature before processing the event. The signed payload is `<timestamp>.<raw_json_body>` using the endpoint signing secret.