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

# Notifications API Overview

> Reference overview of the Notifications API — webhook subscriptions, delivery monitoring and event schemas.

This page is a reference overview of the Notifications API — the webhook subscription system that backs real-time, event-driven integrations with the Catena platform. It covers creating and managing subscriptions, inspecting delivery logs, replaying failed events, and reading versioned event schemas.

It is not a release entry: these endpoints were introduced across many releases, and the Notifications API has been documented since November 2025. For dated changes, see the [changelog index](/api-reference/changelogs).

<Check>
  **Base URL:** The Notifications API is served at `https://api.catenatelematics.com/v2/notifications/`. All endpoints require Bearer token authentication.
</Check>

***

## Webhook Subscriptions

<AccordionGroup>
  <Accordion title="Subscription management endpoints" icon="webhook">
    A full CRUD interface for managing webhook subscriptions.

    **Added:**

    * `GET /v2/notifications/webhooks` — List all webhook subscriptions with filtering and cursor-based pagination
    * `POST /v2/notifications/webhooks` — Create a new webhook subscription
    * `GET /v2/notifications/webhooks/{webhook_id}` — Retrieve a single webhook subscription by ID
    * `PATCH /v2/notifications/webhooks/{webhook_id}` — Update an existing webhook subscription
    * `DELETE /v2/notifications/webhooks/{webhook_id}` — Delete a webhook subscription

    ```bash theme={null}
    # Create a webhook subscription
    POST /v2/notifications/webhooks
    Authorization: Bearer <token>
    Content-Type: application/json

    {
      "url": "https://your-app.example.com/webhooks",
      "events": ["vehicle.modified", "hos_violation.added"],
      "filters": {}
    }
    ```
  </Accordion>

  <Accordion title="Lifecycle management endpoints" icon="toggle-on">
    Control the active state of webhook subscriptions without deleting them.

    **Added:**

    * `POST /v2/notifications/webhooks/{webhook_id}/pause` — Pause a webhook subscription to temporarily stop event delivery
    * `POST /v2/notifications/webhooks/{webhook_id}/activate` — Reactivate a paused or stale webhook subscription

    ```bash theme={null}
    # Reactivate a stale webhook
    POST /v2/notifications/webhooks/{webhook_id}/activate
    Authorization: Bearer <token>
    ```
  </Accordion>
</AccordionGroup>

***

## Delivery Monitoring & Replay

<AccordionGroup>
  <Accordion title="Logs and metrics endpoints" icon="chart-bar">
    Inspect delivery history and track webhook health over time.

    **Added:**

    * `GET /v2/notifications/webhooks/{webhook_id}/logs` — Retrieve paginated delivery attempt logs for a webhook
    * `GET /v2/notifications/webhooks/{webhook_id}/metrics` — Retrieve aggregated delivery metrics (success rates, failure counts, time-period breakdowns)

    ```bash theme={null}
    # Fetch delivery logs
    GET /v2/notifications/webhooks/{webhook_id}/logs
    Authorization: Bearer <token>
    ```
  </Accordion>

  <Accordion title="Event replay endpoint" icon="rotate-left">
    Recover events from the Dead Letter Queue after outages or delivery failures.

    **Added:**

    * `POST /v2/notifications/webhooks/{webhook_id}/replay` — Replay failed events stored in the Dead Letter Queue

    ```bash theme={null}
    # Replay failed events
    POST /v2/notifications/webhooks/{webhook_id}/replay
    Authorization: Bearer <token>
    Content-Type: application/json

    {
      "from": "2026-08-01T00:00:00Z",
      "to": "2026-08-05T00:00:00Z"
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Event Schemas

<AccordionGroup>
  <Accordion title="Schema discovery endpoints" icon="book">
    Access versioned OpenAPI 3.0 schemas for all webhook event types.

    **Added:**

    * `GET /v2/notifications/schemas/{event_name}` — Retrieve the schema definition for a specific event type
    * `GET /v2/notifications/schemas/{event_name}/versions/{version}` — Retrieve a specific historical version of an event schema

    ```bash theme={null}
    # Get schema for vehicle.modified event
    GET /v2/notifications/schemas/vehicle.modified
    Authorization: Bearer <token>
    ```
  </Accordion>
</AccordionGroup>

***

## Supported Event Types

The API supports the following webhook event categories:

| Category | Example Events |
| - | - |
| **Telematics** | `vehicle.added`, `vehicle.modified`, `vehicle.removed`, `vehicle_location.added` |
| **HOS & Compliance** | `hos_event.added`, `hos_violation.added`, `hos_availability.added`, `dvir_log.added` |
| **Driver & Fleet** | `driver_vehicle_association.added`, `fleet_info.added`, `fleet_connection.created` |
| **Organizational** | `invitation.sent`, `share_agreement.created`, `tsp.created` |
| **System** | `webhook.staled`, `webhook.deleted`, `execution.failed`, `connection.staled` |
| **Reefer & Trailers** | `trailer.added`, `trailer_status.added`, `trailer_location.added` |
| **Fuel & IFTA** | `fuel_transaction.added`, `ifta_summary.added` |
| **Workflows & Messages** | `workflow.added`, `group_message.added` |

***

## Schemas

The API defines over 200 schemas covering the full webhook event catalog, including:

* **Webhook management**: `WebhookRead`, `WebhookCreate`, `WebhookUpdate`, `WebhookMetrics`, `WebhookLogRead`
* **Event envelopes**: `BaseWebhookEvent`, `BaseExecutionEvent`, `BaseConnectionEvent`
* **Telematics events**: `VehicleAdded`, `VehicleModified`, `VehicleLocationAdded`, `EngineStatusAdded`, `EngineLogAdded`
* **HOS events**: `HosEventAdded`, `HosViolationAdded`, `HosDailySnapshotAdded`, `HosAvailabilityAdded`
* **Organizational events**: `InvitationSent`, `ShareAgreementCreated`, `FleetConnectionCreated`, `TspCreated`
* **Error responses**: `BadRequest`, `Unauthorized`, `Forbidden`, `NotFound`, `Conflict`, `TooManyRequests`, `InternalServerError`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.