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

# Register Webhook

> Register a webhook endpoint to receive event notifications

Register a URL to receive webhook notifications when jobs or batches complete.

<ParamField body="url" type="string" required>
  HTTPS URL to receive webhook events. Must use HTTPS.
</ParamField>

<ParamField body="events" type="string[]" default="[&#x22;job.completed&#x22;, &#x22;job.failed&#x22;, &#x22;batch.completed&#x22;, &#x22;batch.failed&#x22;]">
  Event types to subscribe to: `job.completed`, `job.failed`, `batch.completed`,
  `batch.failed`, `batch.progress`.

  `batch.progress` is **not** in the default set — a large batch emits several, so
  it is opt-in. It fires at most once per 10% of a batch and never for batches
  under 5 videos.

  Unknown event names are rejected with `400 invalid_events`. That includes names
  reserved for future releases (`video.transcribed`, `video.indexed`,
  `readiness.flagged`) — better a clear error than a subscription that never fires.
</ParamField>

<ParamField body="description" type="string">
  Optional description (max 255 characters).
</ParamField>

### Response (201 Created)

<ResponseField name="id" type="string">
  Webhook endpoint UUID.
</ResponseField>

<ResponseField name="url" type="string">
  Registered URL.
</ResponseField>

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

<ResponseField name="secret" type="string">
  HMAC signing secret (64-char hex). **Save this — it is only shown here.**
  [List Webhooks](/api-reference/list-webhooks) returns just an 8-character prefix.
  If you lose it, use [Rotate Secret](/api-reference/rotate-webhook-secret) rather
  than re-registering. Used to [verify signatures](/guides/webhooks#verifying-signatures).
</ResponseField>

<ResponseField name="payload_version" type="string">
  Always `v1` for newly registered endpoints — the documented envelope. Endpoints
  registered before 2026-08-15 are pinned to `legacy` and keep receiving the older
  flat payload. See [Webhooks](/guides/webhooks).
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the webhook is active.
</ResponseField>

**Limits:** Maximum 5 active webhooks per API key. URLs must use HTTPS.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.fastdrop.io/api/v1/webhooks \
    -H "Content-Type: application/json" \
    -H "X-API-Key: fd_live_your_key_here" \
    -d '{
      "url": "https://your-server.com/webhooks/fastdrop",
      "events": ["job.completed", "job.failed"],
      "description": "Production webhook"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "3f9a1c22-8e4b-4d7a-9c11-77d2f0b5a8e3",
    "url": "https://your-server.com/webhooks/fastdrop",
    "events": ["job.completed", "job.failed"],
    "description": "Production webhook",
    "secret": "a1b2c3d4e5f6789...64_char_hex_string",
    "payload_version": "v1",
    "is_active": true,
    "created_at": "2026-08-15T12:00:00Z"
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.