Receiving

When an event occurs, Cobalt will send a POST request to your webhook URL with a JSON payload. The payload will include information about the event that occurred.

Payload Envelope

Every delivery is a JSON object describing one event. Cobalt sends three closely related envelope variants:

Operation events confirm actions Cobalt performed in the EHR (for example appointment.created, patient.updated, test.event). They carry object: "event", a created timestamp, and action: "cobalt_operation".
EHR sync events report changes Cobalt detected in the EHR (for example appointment.updated, patient.created, the *.synced events). Same shape as operation events, but action: "ehr_sync".
Live-fetch events (appointment.live_fetch_completed, availability.live_fetch_completed, patient.live_fetch_completed) report the result of an on-demand fetch. They carry object: "event" and created, the same as every other event, and use action: "sync". For backward compatibility they also include a timestamp field, a legacy alias of created; prefer created. They always fire when the fetch completes, regardless of your event subscriptions.

Operation / sync event:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "7b4e9f21-c83a-4d56-b107-332f8a1c0e94",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "appointment.created",
  "job_id": "12345",
  "action": "cobalt_operation",
  "data": { ... }
}

Live-fetch event:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "7b4e9f21-c83a-4d56-b107-332f8a1c0e94",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "job_id": "12345",
  "type": "appointment.live_fetch_completed",
  "action": "sync",
  "timestamp": "2025-10-21T14:30:00.000Z",
  "data": { ... }
}

Every delivery, including live-fetch events, carries id, object (always "event"), created, type, data, and access_token_reference_id. Live-fetch events additionally include a timestamp field, a legacy alias of created retained for backward compatibility; new integrations should read created. You can also read webhook-timestamp from the request headers, which is present on every delivery. Use access_token_id to attribute an event to a specific connection under your account.

Headers

Every webhook request includes the following headers:

Header	Description
`cobalt-verification`	HMAC-SHA256 signature of the payload for verifying authenticity
`webhook-id`	Unique event identifier — use this to deduplicate deliveries
`webhook-timestamp`	ISO 8601 timestamp of when the event was created
`webhook-attempt`	Delivery attempt number (starting at `1`)

Verifying Signatures

To ensure the webhook is coming from Cobalt, validate the cobalt-verification signature before processing the payload:

const crypto = require('crypto');

function verifySignature(payload, signature, secretKey) {
    const expectedSignature = crypto.createHmac('sha256', secretKey)
        .update(JSON.stringify(payload))
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
}

// In your webhook handler
app.post('/webhook', (req, res) => {
    const payload = req.body;
    const signature = req.headers['cobalt-verification'];

    if (!verifySignature(payload, signature, YOUR_WEBHOOK_SECRET_KEY)) {
        return res.status(401).send('Invalid signature');
    }

    // Deduplicate using webhook-id
    const webhookId = req.headers['webhook-id'];
    if (alreadyProcessed(webhookId)) {
        return res.status(200).send('Already processed');
    }

    // Process the webhook payload
    console.log('Received valid webhook:', payload);

    res.status(200).send('Webhook received');
});

Retry Behavior

If your endpoint returns a 5xx status code or a network error occurs, Cobalt will retry delivery once (2 total attempts) with a 1-second delay. The retry uses a shorter 2-second timeout since your server should already be warm. Each retry increments the webhook-attempt header. Cobalt does not retry on:

4xx status codes (except 429) — these indicate a client-side configuration issue
Timeouts — if your server received the request but was slow to respond, retrying could cause duplicate processing

Return a 2xx response as quickly as possible. Process the event asynchronously to avoid timeouts. If your endpoint takes longer than 5 seconds to respond, the request will time out.

Introduction

Guides

Payload Envelope

Headers

Verifying Signatures

Retry Behavior

​Payload Envelope

​Headers

​Verifying Signatures

​Retry Behavior

Payload Envelope

Headers

Verifying Signatures

Retry Behavior