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

# Webhooks Overview

> Push-based notifications for commentary approval workflow events

# Webhooks

Webhooks provide real-time push notifications when commentary approval events occur, eliminating the need for polling.

## Benefits

* **Near real-time updates**: Receive notifications within seconds of approval events
* **Reduced polling**: No need to repeatedly check status endpoints
* **Reliable delivery**: Automatic retries with exponential backoff
* **Secure**: HMAC-SHA256 signed payloads

## Event Types

| Event               | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `creator.approved`  | Creator has approved their commentary — ready for partner review |
| `partner.approved`  | Partner has approved the commentary — ready for distribution     |
| `commentary.failed` | Commentary generation failed or was rejected                     |

## Webhook Payload Structure

```json theme={null}
{
  "id": "evt_abc123",
  "type": "creator.approved",
  "created_at": "2026-02-04T10:00:00Z",
  "data": {
    "topic_id": "uuid",
    "external_reference": "your-content-id",
    "persona_id": "uuid",
    "persona_name": "Persona Name",
    "commentary": {
      "id": "uuid",
      "content": "The commentary text...",
      "audio_url": "https://cdn.unleeshed.ai/audio/...",
      "video_url": null
    },
    "metadata": {
      "your": "custom data"
    }
  }
}
```

## Security

All webhook payloads are signed with HMAC-SHA256. The signature is included in the `X-Unleeshed-Signature` header:

```
X-Unleeshed-Signature: t=1707000000,v1=5f2b...
```

See [Webhook Integration Guide](/guides/webhook-integration) for verification code.

## Required Scopes

* `webhooks:manage` - Create, update, delete webhooks
* `webhooks:read` - List webhooks and delivery logs

## Next Steps

<CardGroup cols={2}>
  <Card title="Register Webhook" icon="plus" href="/api-reference/webhooks/register">
    Create your first webhook
  </Card>

  <Card title="Integration Guide" icon="book" href="/guides/webhook-integration">
    Complete setup instructions
  </Card>
</CardGroup>