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

# Create Webhook

> Register a new webhook endpoint for real-time event delivery

Register a new webhook endpoint to receive real-time events when tracked sources post new content.

## Request

<ParamField body="url" type="string" required>
  The HTTPS endpoint URL where events will be delivered.
</ParamField>

<ParamField body="name" type="string">
  Optional name for the webhook for easy identification.
</ParamField>

## Response

<ResponseField name="data" type="object">
  The created webhook object
</ResponseField>

<ResponseField name="message" type="string">
  Status message describing the result
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://scrape.st/webhook \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-domain.com/webhook",
      "name": "My Webhook"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": {
      "id": "wh_abc123",
      "apiKey": "sk_live_xxx",
      "name": "My Webhook",
      "url": "https://your-domain.com/webhook",
      "status": "ACTIVE"
    },
    "message": "Webhook registered successfully"
  }
  ```
</ResponseExample>

## Delivery & Failure Handling

Each event is delivered as an HTTP `POST` with a JSON body and a 5-second timeout. Scrapest retries transient failures with exponential backoff, but to protect your endpoint and our delivery pipeline it will **automatically pause** a webhook that keeps failing.

The `status` field reflects this:

| Status   | Meaning                                                            |
| -------- | ------------------------------------------------------------------ |
| `ACTIVE` | Delivering normally.                                               |
| `FAILED` | Auto-paused — no further events are delivered until you re-enable. |

A webhook is moved to `FAILED` when either:

* Your endpoint returns **404** or **410** (gone) on a delivery — paused immediately, since the URL is treated as permanently removed, **or**
* It accumulates **5 consecutive delivery failures** within a 24-hour window (timeouts, 5xx, connection errors, etc.).

<Note>
  To resume a paused webhook, **re-register** it (`POST /webhook`) or **update**
  it ([PATCH /webhook](/rest-api-reference/update-webhook)) — both reset
  `status` back to `ACTIVE` and restart delivery. Make sure your endpoint
  responds with a `2xx` status and within 5 seconds to stay active.
</Note>