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:

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:

{
  "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:

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:

{
  "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:

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:

{
    "success": true,
    "message": "Webhook URL removed successfully"
}

Rotate Secret

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

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:

{
  "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):

{
  // ...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.

Introduction

Guides

Setting up Webhooks

Register

Get Configuration

Remove a Webhook URL

Rotate Secret

Overriding the Destination Per Request

​Setting up Webhooks

​Register

​Get Configuration

​Remove a Webhook URL

​Rotate Secret

​Overriding the Destination Per Request

Setting up Webhooks

Register

Get Configuration

Remove a Webhook URL

Rotate Secret

Overriding the Destination Per Request