Get Webhook Events - Documentation

List webhook events

curl --request GET \
  --url https://api.usecobalt.com/v1/webhook-events \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

url = "https://api.usecobalt.com/v1/webhook-events"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/webhook-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/webhook-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/webhook-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/webhook-events")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/webhook-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "webhook_events": [
    {
      "event_id": "<string>",
      "event_type": "<string>",
      "webhook_url": "<string>",
      "data": {},
      "created_at": "2023-11-07T05:31:56Z",
      "job_id": "<string>",
      "access_token_reference_id": "<string>"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 151,
    "page_size": 100
  }
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

GET

webhook-events

List webhook events

curl --request GET \
  --url https://api.usecobalt.com/v1/webhook-events \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

url = "https://api.usecobalt.com/v1/webhook-events"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/webhook-events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/webhook-events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/webhook-events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/webhook-events")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/webhook-events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "webhook_events": [
    {
      "event_id": "<string>",
      "event_type": "<string>",
      "webhook_url": "<string>",
      "data": {},
      "created_at": "2023-11-07T05:31:56Z",
      "job_id": "<string>",
      "access_token_reference_id": "<string>"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 151,
    "page_size": 100
  }
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

{
  "success": true,
  "message": "<string>"
}

Use this endpoint to retrieve webhook events that have been sent to your registered webhook URLs.

Use Cases

Debug webhook delivery issues
Audit webhook event history
Recover missed webhook events after downtime
Verify event payloads during integration testing

Common Event Types

patient.insurance.added - Insurance successfully added to patient
patient.insurance.failed - Insurance addition failed
appointment.created - Appointment created
appointment.updated - Appointment updated
note.created - Clinical note created

Query Parameters

job_id (string, optional): Filter by job ID. Returns only events associated with a specific asynchronous operation. Useful for awaiting results of a single API call.
event_type (string, optional): Filter by event type (e.g., “patient.insurance.added”, “appointment.created”)
delivery_status (string, optional): Filter by delivery status - “success” or “failed”. Indicates whether the webhook event was delivered to the webhook URL on file
start_date (string, optional): Filter events created on or after this date (ISO 8601 format: YYYY-MM-DD)
end_date (string, optional): Filter events created on or before this date (ISO 8601 format: YYYY-MM-DD)
page (integer, optional): Page number (default: 1, min: 1)
page_size (integer, optional): Number of events per page (default: 50, max: 100)
sort (string, optional): Sort order. Use “created_at” for ascending (oldest first) or “-created_at” for descending (newest first). Default: “-created_at”

Common Workflows

Track Appointments You Created via the API

To track all appointments you’ve successfully created through Cobalt’s API, filter by appointment.created events:

curl -X GET "https://api.usecobalt.com/v1/webhook-events?event_type=appointment.created&start_date=2025-01-01" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

This returns all successful appointment creations since January 1, 2025. Each event includes the appointment_id, patient MRN, date/time, and provider information - allowing you to maintain a complete audit trail of appointments scheduled through your integration. Response:

{
  "success": true,
  "webhook_events": [
    {
      "event_id": "evt_xyz789ghi012",
      "event_type": "appointment.created",
      "webhook_url": "https://your-webhook-url.com/webhooks",
      "delivery_status": "success",
      "data": {
        "appointment_id": "appt123456789",
        "date_time": "2025-01-20T14:30:00",
        "timezone": "America/Los_Angeles",
        "provider_id": "prov_456",
        "secondary_provider_id": null,
        "provider_name": "Dr. Jane Smith",
        "mrn": "MRN123456"
      },
      "created_at": "2025-01-15T11:00:00.000Z",
      "job_id": "67890",
      "access_token_reference_id": "your_reference_id"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 243,
    "page_size": 50
  }
}

Additional Example Requests

Get Recent Events

curl -X GET "https://api.usecobalt.com/v1/webhook-events?page_size=20" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

Filter by Event Type

curl -X GET "https://api.usecobalt.com/v1/webhook-events?event_type=patient.insurance.added&page_size=10" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

Filter by Date Range

curl -X GET "https://api.usecobalt.com/v1/webhook-events?start_date=2025-01-01&end_date=2025-01-31" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

Get Page 2

curl -X GET "https://api.usecobalt.com/v1/webhook-events?page=2&page_size=50" \
  -H "client_id: your_client_id" \
  -H "client_secret: your_client_secret" \
  -H "access_token: your_access_token"

Example Response

Patient Insurance Added Event

{
  "success": true,
  "webhook_events": [
    {
      "event_id": "evt_abc123def456",
      "event_type": "patient.insurance.added",
      "webhook_url": "https://your-webhook-url.com/webhooks",
      "delivery_status": "success",
      "data": {
        "patient_insurance_id": "xyz789abc123",
        "patient_mrn": "MRN123456"
      },
      "created_at": "2025-01-15T10:30:00.000Z",
      "job_id": "12345",
      "access_token_reference_id": "your_reference_id"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "total_count": 487,
    "page_size": 50
  }
}

Response Fields

Top-Level Fields

success (boolean): Whether the request was successful
webhook_events (array): Array of webhook event objects
pagination (object): Pagination metadata

Event Object Fields

event_id (string): Unique event identifier
event_type (string): Event type (e.g., “patient.insurance.added”, “appointment.created”)
webhook_url (string): The URL the event was sent to
delivery_status (string): Delivery status - “success” or “failed”. Indicates whether the webhook event was delivered to the webhook URL on file
data (object): Event-specific payload data
created_at (string): ISO 8601 timestamp of event creation
job_id (string, nullable): Job ID if this event is related to an asynchronous operation
access_token_reference_id (string, nullable): The reference ID associated with your access token

Pagination Object

current_page (integer): Current page number
total_pages (integer): Total number of pages
total_count (integer): Total number of events matching the filter
page_size (integer): Number of items per page

The data field in each event contains event-specific information that varies depending on the event type. Refer to the webhook event docs for payload structures: Operation Events, Sync Events, Account Events.

Pagination

This endpoint supports page-based pagination:

Make an initial request with optional page and page_size parameters
Check the pagination object in the response for total_pages
Request subsequent pages by incrementing the page parameter
Continue until you reach total_pages

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Query Parameters

job_id

integer

Filter webhook events by a specific job ID. Useful for polling the result of an asynchronous operation

event_type

string

Filter by event type (e.g., "patient.insurance.added", "appointment.created")

delivery_status

enum<string>

Filter by delivery status - "success" or "failed". Indicates whether the webhook event was delivered to the webhook URL on file

Available options:

success,

failed

start_date

string<date>

Filter events created on or after this date (ISO 8601 format: YYYY-MM-DD)

end_date

string<date>

Filter events created on or before this date (ISO 8601 format: YYYY-MM-DD)

page

integer

default:1

Page number (default: 1, min: 1)

Required range: x >= 1

page_size

integer

default:50

Number of events per page (default: 50, max: 100)

Required range: 1 <= x <= 100

sort

enum<string>

default:-created_at

Sort order. Use 'created_at' for ascending (oldest first) or '-created_at' for descending (newest first). Default: '-created_at'

Available options:

created_at,

-created_at

Response

Successful response with pagination

success

boolean

webhook_events

object[]

Show child attributes

pagination

object

Show child attributes

Rotate Webhook Secret

​Use Cases

​Common Event Types

​Query Parameters

​Common Workflows

​Track Appointments You Created via the API

​Additional Example Requests

​Get Recent Events

​Filter by Event Type

​Filter by Date Range

​Get Page 2

​Example Response

​Patient Insurance Added Event

​Response Fields

​Top-Level Fields

​Event Object Fields

​Pagination Object

​Pagination

Authorizations

Query Parameters

Response

Use Cases

Common Event Types

Query Parameters

Common Workflows

Track Appointments You Created via the API

Additional Example Requests

Get Recent Events

Filter by Event Type

Filter by Date Range

Get Page 2

Example Response

Patient Insurance Added Event

Response Fields

Top-Level Fields

Event Object Fields

Pagination Object

Pagination