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

# Create Webhook

> Subscribe to extraction events with a webhook URL

Create a new webhook subscription. The response includes a `secret` for verifying webhook signatures. This secret is only returned on creation and cannot be retrieved later.

## Request Body

| Field    | Type      | Required | Default    | Description                                                                       |
| -------- | --------- | -------- | ---------- | --------------------------------------------------------------------------------- |
| `url`    | string    | Yes      | —          | HTTPS URL to receive webhook events. HTTP URLs are rejected.                      |
| `events` | string\[] | No       | All events | Array of event types to subscribe to: `extraction.completed`, `extraction.failed` |

<Warning>
  The `secret` field is only included in the creation response. Store it immediately. If lost, delete the webhook and create a new one.
</Warning>

<RequestExample>
  ```bash curl theme={null}
  curl -X POST 'https://api.anyformat.ai/v2/webhooks/' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://your-server.com/webhooks/anyformat",
      "events": ["extraction.completed", "extraction.failed"]
    }'
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.anyformat.ai/v2/webhooks/"
  headers = {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
  }

  data = {
      "url": "https://your-server.com/webhooks/anyformat",
      "events": ["extraction.completed", "extraction.failed"]
  }

  response = requests.post(url, headers=headers, json=data)
  webhook = response.json()
  # Store the secret securely — it is only returned on creation
  print(f"Webhook created: {webhook['id']}, secret: {webhook['secret']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.anyformat.ai/v2/webhooks/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify({
      url: 'https://your-server.com/webhooks/anyformat',
      events: ['extraction.completed', 'extraction.failed']
    })
  });

  const data = await response.json();
  // Store the secret securely — it is only returned on creation
  console.log(data);
  ```

  ```typescript TypeScript theme={null}
  interface WebhookCreateRequest {
    url: string;
    events?: string[];
  }

  interface WebhookResponse {
    id: string;
    url: string;
    events: string[];
    is_active: boolean;
    secret: string;
    created_at: string;
  }

  const body: WebhookCreateRequest = {
    url: 'https://your-server.com/webhooks/anyformat',
    events: ['extraction.completed', 'extraction.failed']
  };

  const response = await fetch('https://api.anyformat.ai/v2/webhooks/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  const data: WebhookResponse = await response.json();
  // Store data.secret securely — it is only returned on creation
  console.log(data.id);
  ```
</RequestExample>

<ResponseExample>
  ```json Response (201 Created) theme={null}
  {
    "id": "wh_1234567890",
    "url": "https://your-server.com/webhooks/anyformat",
    "events": ["extraction.completed", "extraction.failed"],
    "is_active": true,
    "secret": "whsec_abc123def456...",
    "created_at": "2024-03-24T12:00:00.000Z"
  }
  ```
</ResponseExample>