> ## 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.

# Register Webhook

> Register a new webhook endpoint

Register a webhook endpoint to receive event notifications.

<Warning>
  The webhook secret is only returned in this response. Store it securely for signature verification.
</Warning>

## Request Body

<ParamField body="url" type="string" required>
  HTTPS URL to receive webhook POST requests
</ParamField>

<ParamField body="events" type="string[]" required>
  Events to subscribe to. Valid values: `creator.approved`, `partner.approved`, `commentary.failed`
</ParamField>

<ParamField body="secret" type="string">
  Optional custom secret (min 32 chars). If not provided, one is generated.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique webhook ID
</ResponseField>

<ResponseField name="url" type="string">
  The registered webhook URL
</ResponseField>

<ResponseField name="events" type="string[]">
  Subscribed event types
</ResponseField>

<ResponseField name="secret" type="string">
  Webhook signing secret (only returned on creation)
</ResponseField>

<ResponseField name="status" type="string">
  Webhook status: `active`, `paused`, or `disabled`
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://prod.api.unleeshed.ai/partner/v1/webhooks \
    -H "X-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-domain.com/webhooks/unleeshed",
      "events": ["creator.approved", "partner.approved", "commentary.failed"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "whk_abc123",
      "url": "https://your-domain.com/webhooks/unleeshed",
      "events": ["creator.approved", "partner.approved", "commentary.failed"],
      "secret": "whsec_a1b2c3d4...",
      "status": "active",
      "consecutive_failures": 0,
      "last_delivery_at": null,
      "created_at": "2026-02-04T10:00:00Z",
      "updated_at": "2026-02-04T10:00:00Z"
    }
  }
  ```
</ResponseExample>