> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Webhook Events

> Retrieve webhook events sent to your registered webhook URLs.

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](/docs/awaiting-results/overview) 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:

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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

<Note>
  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](/docs/webhooks/operation-events), [Sync Events](/docs/webhooks/sync-events), [Account Events](/docs/webhooks/account-events).
</Note>

## Pagination

This endpoint supports page-based 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`


## OpenAPI

````yaml GET /webhook-events
openapi: 3.0.0
info:
  title: Cobalt API
  version: 1.0.1
  description: API for interacting with Cobalt's EHR integration services
servers:
  - url: https://api.usecobalt.com/v1
security:
  - ClientCredentials: []
    ClientSecret: []
    AccessToken: []
paths:
  /webhook-events:
    get:
      tags:
        - Webhooks
      summary: List webhook events
      description: >-
        Retrieve webhook events sent to your registered webhook URL. Useful for
        debugging, auditing, or recovering from webhook delivery failures.
      operationId: getWebhookEvents
      parameters:
        - in: query
          name: job_id
          schema:
            type: integer
          description: >-
            Filter webhook events by a specific job ID. Useful for polling the
            result of an asynchronous operation
        - in: query
          name: event_type
          schema:
            type: string
          description: >-
            Filter by event type (e.g., "patient.insurance.added",
            "appointment.created")
        - in: query
          name: delivery_status
          schema:
            type: string
            enum:
              - success
              - failed
          description: >-
            Filter by delivery status - "success" or "failed". Indicates whether
            the webhook event was delivered to the webhook URL on file
        - in: query
          name: start_date
          schema:
            type: string
            format: date
          description: >-
            Filter events created on or after this date (ISO 8601 format:
            YYYY-MM-DD)
        - in: query
          name: end_date
          schema:
            type: string
            format: date
          description: >-
            Filter events created on or before this date (ISO 8601 format:
            YYYY-MM-DD)
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            minimum: 1
          description: 'Page number (default: 1, min: 1)'
        - in: query
          name: page_size
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: 'Number of events per page (default: 50, max: 100)'
        - in: query
          name: sort
          schema:
            type: string
            enum:
              - created_at
              - '-created_at'
            default: '-created_at'
          description: >-
            Sort order. Use 'created_at' for ascending (oldest first) or
            '-created_at' for descending (newest first). Default: '-created_at'
      responses:
        '200':
          description: Successful response with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  webhook_events:
                    type: array
                    items:
                      type: object
                      properties:
                        event_id:
                          type: string
                          description: Unique event identifier
                        event_type:
                          type: string
                          description: >-
                            Event type (e.g., "patient.insurance.added",
                            "appointment.created")
                        webhook_url:
                          type: string
                          description: The URL the event was sent to
                        delivery_status:
                          type: string
                          enum:
                            - success
                            - failed
                          description: >-
                            Delivery status - "success" or "failed". Indicates
                            whether the webhook event was delivered to the
                            webhook URL on file
                        data:
                          type: object
                          description: Event-specific payload data
                        created_at:
                          type: string
                          format: date-time
                          description: ISO 8601 timestamp of event creation
                        job_id:
                          type: string
                          nullable: true
                          description: >-
                            Job ID if this event is related to an asynchronous
                            operation
                        access_token_reference_id:
                          type: string
                          nullable: true
                          description: The reference ID associated with your access token
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        description: Current page number
                        example: 1
                      total_pages:
                        type: integer
                        description: Total number of pages
                        example: 2
                      total_count:
                        type: integer
                        description: Total number of items
                        example: 151
                      page_size:
                        type: integer
                        description: Number of items per page
                        example: 100
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
components:
  securitySchemes:
    ClientCredentials:
      type: apiKey
      in: header
      name: client_id
    ClientSecret:
      type: apiKey
      in: header
      name: client_secret
    AccessToken:
      type: apiKey
      in: header
      name: access_token

````