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

# Webhooks

> Get async job completion updates through your own HTTPS endpoint

Some async endpoints support optional webhook delivery. When supported, the request body includes a `webhook_url` field.

If an endpoint does not show `webhook_url` in its request body schema, webhooks are not available for that endpoint.

## How to enable

For supported endpoints, include your HTTPS URL in `webhook_url` when creating the job:

```json theme={null}
{
  "input": {
    "...": "..."
  },
  "webhook_url": "https://your-app.com/webhooks/tokenkit"
}
```

## Delivery behavior

When a job reaches a terminal state, TokenKit sends a `POST` request to your `webhook_url` with JSON:

```json theme={null}
{
  "job_id": "job_abc123",
  "status": "succeeded",
  "data": {
    "...": "endpoint-specific output"
  }
}
```

* `status` is `succeeded` or `failed`
* `data` contains the final job result or failure payload for that endpoint

## Reliability and retry logic

Webhook delivery uses fire-and-forget semantics so your original API request is never blocked by webhook failures:

* Only `https://` URLs are allowed; non-HTTPS URLs are skipped
* Request method is `POST` with `Content-Type: application/json`
* Each attempt has a 10 second timeout
* Non-2xx responses are treated as failures and retried
* Up to 5 total attempts are made (initial try + 4 retries)
* Retries use exponential backoff starting at 1 second (1s, 2s, 4s, 8s)

## Implementation notes

* Return a fast `2xx` response from your webhook handler to avoid unnecessary retries
* Design your endpoint to be idempotent in case of repeated delivery attempts