​
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

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

​
Advanced Webhook Settings

In Cobalt webhooks, you can configure advanced settings such as any headers or body that you want to send to the Webhook URL.

For example, to fire the Workflow API of Cobalt to execute a workflow when some event occurs in Cobalt. You will simply add the headers and Body too if required.

To use Advanced Settings, remember to choose Custom as the Webhook template while registering.

​
Templating Webhook Payload variables

You can also use the payload data of a webhook by templating it in your body or headers of Webhooks. If a workflow with Response node in it has executed successfully and you want to use its response data during webhook firing, you can template that in your headers or body.

The format to template is:

{{event.<payload_key_name>}}  // When you want to use a variable from the payload
{{event.instance_id}} // Example of using Instance ID from Workflow Errored payload

{{workflow_response}}  // In case you want to access complete Response Node payload
{{workflow_response.<key_name>}} // To access any key inside the response node payload

​
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.