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

# Setup

## Setting up Webhooks

To use webhooks, you need to set up a webhook endpoint URL in your application that can receive POST requests from Cobalt. This URL should be publicly accessible and use HTTPS for security. You can set up multiple webhook urls (eg. one for development and one for production) and Cobalt will send the same webhook event to each url.

### Register

To register a new webhook, POST `/v1/webhook`.

Example request:

```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/webhook \
-H 'Content-Type: application/json' \
-H 'client_id: "%COBALT_CLIENT_ID%"' \
-H 'client_secret: "%COBALT_CLIENT_SECRET%"' \
-d '{
"webhook_url": "https://your-domain.com/webhook" // https is required
}'
```

Example response:

```bash theme={null}
{
  "success": true,
  "message": "Webhook registered successfully",
  "webhook_secret_key": "your_webhook_secret_key"
}
```

### Get  Configuration

To retrieve your current webhook configuration, GET `/v1/webhook`.

Example request:

```bash theme={null}
curl -X GET https://api.usecobalt.com/v1/webhook \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh'
```

Example response:

```bash theme={null}
{
  "success": true,
  "webhook_url": "https://your-domain.com/webhook",
  "webhook_urls": [
        {
            "id": "987654321",
            "url": "https://dev.your-domain.com/cobalt-webhook"
        },
        {
            "id": "123456789",
            "url": "https://your-domain.com/cobalt-webhook"
        }
  ],
  "webhook_secret_key": "your_webhook_secret_key"
}
```

### Remove a Webhook URL

To remove a webhook url, DELETE `/v1/webhook/:id`.

Example request:

```bash theme={null}
curl -X DELETE https://api.usecobalt.com/v1/webhook/987654321 \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh'
```

Example response:

```bash theme={null}
{
    "success": true,
    "message": "Webhook URL removed successfully"
}
```

### Rotate Secret

To rotate your webhook secret key, POST `/v1/webhook/rotate-secret`.

```bash theme={null}
curl -X POST https://api.usecobalt.com/v1/webhook/rotate-secret \
-H 'Content-Type: application/json' \
-H 'client_id: "%COBALT_CLIENT_ID%"' \
-H 'client_secret: "%COBALT_CLIENT_SECRET%"'
```

Example response:

```bash theme={null}
{
  "success": true,
  "message": "Webhook secret rotated successfully",
  "webhook_secret_key": "your_new_webhook_secret_key"
}
```

## Overriding the Destination Per Request

By default, every event is delivered to all of your registered webhook URLs. To route the events for a single operation somewhere else instead, include a `callback_urls` array in the body of any asynchronous request (the `POST` and `PATCH` endpoints that return a `job_id`):

```json theme={null}
{
  // ...your normal request fields...
  "callback_urls": ["https://your-domain.com/cobalt-webhook"] // https is required
}
```

When `callback_urls` is provided, the completion event for that operation is delivered only to those URLs and not to your registered account URLs. Omit it and delivery is unchanged. Each URL must use HTTPS.