Get Webhook Events

​

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

• 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

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"

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

​

Pagination

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