​
What are webhooks?

Cobalt webhooks is a method to provide your external applications with real-time information about events in the platform such as Workflow errored or Connection created.

A webhook delivers data to the application at the moment that there is a change, resulting in data being pushed, unlike REST APIs where your application needs to poll the API at regular intervals in order to get the changed data. This makes webhooks much more efficient and friendly.

​
Event Types

Currently Cobalt 5 webhook event types:

​
How to subscribe to webhook events?

There are 2 ways to subscribe to Cobalt events:

  • via the Cobalt’s platform
  • via the Webhook subscription API

​
Via Cobalt’s platform

Go to Dashboard > Developer > Webhooks tab

To create a Webhook subscription, click on + Add Webhook, enter the Webhook URL of the endpoint from your system, and select the desired events you want to receive webhook events for.

Webhooks should use HTTPS and expect to receive POST requests

After you clicked Add Webhook, you are subscribed to the Webhook events.

​
Via the Webhook subscription

You can manage the webhook subscription using our webhooks API. Visit the API reference

​
Verify HMAC Signature

For security purposes, if you require to verify HMAC signature of the Cobalt webhooks you receive, you can easily do so.

It is not necessary to verify the HMAC signature if you do not have a requirement.

Following are the sample codes to verify HMAC signature of Cobalt Webhooks

import * as crypto from 'crypto';

// your Cobalt API key based on environment
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || '<Cobalt-API-key>';
// payload is the data that you receive from the webhook
const payload = {
    "linked_account_id": "dev",
    "instance_id": "67d22c4330d75f3a3fa29056",
    "workflow_id": "67af37ad1d0bb61005439eaf",
    "event": "Workflow Completed",
    "workflow_name": "Get Response",
    "status": "COMPLETED",
    "environment": "test"
}

/**
 * Verifies the HMAC signature from a webhook received from Cobalt
 * @param payload The raw request body as a string (JSON.stringify(payload))
 * @param signature The signature from the webhook header (Header is, 'x-cobalt-signature')
 * @returns boolean indicating if the signature is valid
 */
function verifyWebhookSignature(payload: string, signature: string): boolean {
    try {
        const expectedSignature = crypto
            .createHmac('sha256', WEBHOOK_SECRET)
            .update(payload)
            .digest('hex');

        return crypto.timingSafeEqual(
            Buffer.from(signature, 'hex'),
            Buffer.from(expectedSignature, 'hex')
        );
    } catch (error) {
        console.error('Error verifying webhook signature:', error);
        return false;
    }
}

const examplePayload = JSON.stringify(payload);
const exampleSignature = '42799d46dfd9a8acf35c14e6b7c300cc3734d06a0ce129268f1b54096750a44f'; // This would be from the webhook header x-cobalt-signature

const isValid = verifyWebhookSignature(examplePayload, exampleSignature);
console.log('Signature is valid:', isValid);

​
Receive events

On receiving an event, you should respond with an HTTP 200 OK to signal to Cobalt that the event was successfully delivered. Otherwise, Cobalt will consider the event delivery a failure and retry up to 3 times, with exponential backoff.