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

# Overview

## What are webhooks?

You can set up webhooks to receive real-time notifications from Chunkr whenever task events occur in your account. Ideal for bulk uploads and other high-volume workflows.

Webhooks are HTTPS POST requests sent to an endpoint you control. You can add and manage endpoints from the Chunkr dashboard.
You can use a single endpoint per service that listens to all event types, or restrict it to only the events you care about.

For example, you might receive webhooks from Chunkr at a URL like: `https://www.chunkr.ai/chunkr/webhooks/`.

Indicate that a webhook has been processed by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time frame (15 seconds).

It's also important to disable CSRF protection for this endpoint if your framework enables it by default.

Another important aspect of handling webhooks is verifying the signature and timestamp when processing them.

You can learn more about this in the signature verification section.

## Events & payloads

Chunkr currently emits only 1 event:

* `task.parse.updated`: Webhook event payload for parse task updates

Example payload shape:

<CodeGroup>
  ```javascript Task Parse Updated theme={"system"}
  {
    "event_type": "task.parse.updated",
    "message": null,
    "status": "Starting",
    "task_id": "..."
  }
  ```
</CodeGroup>

<Tip>You can see more information in the [API references](/api-references/task-parse-updated)</Tip>

## Add an endpoint

To start listening to messages, you need to configure your endpoints.

Adding an endpoint is as simple as providing a URL that you control and selecting the event types that you want to listen to.

If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.

This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving extraneous messages.

If your endpoint isn't quite ready to start receiving events, you can click the "Svix Play" button to have a unique URL generated for you.

You'll be able to view and inspect webhooks sent to your Svix Play URL, making it effortless to get started.

<Tip>To add your first endpoint, click the Webhooks section on the [Chunkr dashboard](https://www.chunkr.ai/dashboard)</Tip>

## Test an endpoint

Once you've added an endpoint, you'll want to make sure it's working.

The "Testing" tab lets you send test events to your endpoint.

After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.

### Local testing with Svix Play (CLI)

For local development, you can use [Svix Play](https://docs.svix.com/play) to relay a publicly accessible URL to your local server. Point your Chunkr webhook endpoint to the Play URL, and the CLI will forward requests to your localhost for easy debugging.

1. Install the CLI:

<CodeGroup>
  ```bash macOS theme={"system"}
  brew install svix/svix/svix
  ```

  ```bash Linux theme={"system"}
  snap install svix
  ```

  ```bash Windows theme={"system"}
  scoop bucket add svix https://github.com/svix/scoop-svix.git
  scoop install svix
  ```
</CodeGroup>

2. Start a relay to your local webhook handler:

```bash Start relay theme={"system"}
svix listen http://localhost:8000/webhook/chunkr
# -> Prints: https://play.svix.com/in/<token>/ and a view URL
```

3. In the Chunkr dashboard, set your webhook endpoint URL to the printed Play URL. All messages sent to this URL will be forwarded to your local server.

4. Watch requests in the Svix Play UI (the CLI prints a "view" link) and in your local server logs.

## Verifying webhooks

It’s important to know whether a webhook has come from `chunkr.ai`, or a third party that might be trying to exploit a vulnerability.
To avoid this, we send a signature in the header of our webhooks, which you can verify using a signing secret.

To verify the signatures, see Svix's guide on how to verify webhooks with the [Svix libraries](https://docs.svix.com/receiving/verifying-payloads/how) or how to verify [webhooks manually](https://docs.svix.com/receiving/verifying-payloads/how-manual).

## Retries

We attempt to deliver each webhook message based on a retry schedule with exponential backoff.

### The schedule

Each message is attempted on the following schedule. Each period starts after the preceding attempt fails:

* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)

If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well.

For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.

### Manual retries

You can also use the application portal to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.