> ## 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.

# Webhooks Overview

> Receive real-time event notifications from the Catena platform using webhooks

Webhooks enable your application to receive real-time notifications when events occur within the Catena platform - such as vehicle location updates, safety alerts, or driver status changes. Instead of constantly polling the API for updates, your system provides an HTTPS endpoint that Catena calls automatically whenever an event happens.

<Check>
  **Why Use Webhooks:** Build responsive, event-driven integrations that react instantly to fleet activity without the overhead and latency of constant API polling.
</Check>

***

## How Webhooks Work

<Steps>
  <Step title="Event Occurs" icon="bolt">
    An event (like `vehicle.modified` or `hos_violation.added`) happens within the Catena platform.
  </Step>

  <Step title="Catena Sends Notification" icon="paper-plane">
    Catena sends an HTTP `POST` request to your configured webhook URL with event details in JSON format. Webhook events are typically delivered within **200–500 ms** of the triggering event.
  </Step>

  <Step title="Your System Acknowledges" icon="check">
    Your endpoint receives the event and returns a `202 Accepted` response within 3 seconds to confirm receipt.
  </Step>

  <Step title="Process the Event" icon="gears">
    Your application processes the event data asynchronously—updating records, triggering workflows, or notifying users.
  </Step>
</Steps>

<Tip>
  **Best Practice:** Return `202 Accepted` immediately, then queue the event for background processing. This prevents timeouts and ensures reliable delivery.
</Tip>

***

## Reliability Model

Catena webhooks use an **at-least-once delivery model**. Events are guaranteed to reach your endpoint at least once, but duplicates are possible. Build your integration with this behavior in mind:

<AccordionGroup>
  <Accordion title="At-Least-Once Delivery" icon="repeat">
    Every event is delivered at least once, but duplicates may occur due to retries or network conditions. Use the `X-Request-ID` header and event timestamps to deduplicate events in your application.
  </Accordion>

  <Accordion title="Automatic Retries" icon="arrows-rotate">
    If your endpoint returns a `5xx` error or times out, Catena automatically retries with exponential backoff. Failed events are retried up to 3 times within approximately 5 seconds. After all retries fail, events move to the Dead Letter Queue.

    <Info>
      **Timeout Threshold:** Your endpoint must respond within 3 seconds to avoid timeout failures.
    </Info>
  </Accordion>

  <Accordion title="Out-of-Order Delivery" icon="shuffle">
    Events may arrive out of order due to network conditions and retry logic. Always use the `occurred_at` field inside each record in the event `data` array to determine the correct chronological sequence — not the outer `timestamp`, which reflects when Catena dispatched the delivery.
  </Accordion>

  <Accordion title="Dead Letter Queue (DLQ)" icon="inbox">
    Events that fail all automatic retries are stored in the Dead Letter Queue for up to **14 days**. You can replay these events at any time using the Replay API to recover from temporary outages or issues.

    <Warning>
      Events that occur after the circuit breaker pauses a webhook are **not** queued. The DLQ only contains events that failed delivery while the webhook was still active.
    </Warning>
  </Accordion>

  <Accordion title="Circuit Breaker" icon="bolt-slash">
    Webhooks with persistently low delivery success rates are automatically marked as `stale` and paused to prevent wasted resources. Catena does **not** auto-reactivate paused webhooks — you must explicitly reactivate them after resolving the underlying issue.

    Subscribe to the `webhook.staled` event to get notified immediately when a webhook is paused, or periodically query the List Webhook Subscriptions endpoint filtered by `status=stale`.

    See [Operations & Monitoring](/api-reference/webhooks/operations-monitoring#circuit-breaker) for full details on monitoring, reactivation, and recovery.
  </Accordion>
</AccordionGroup>

<Warning>
  **`.removed` Events Are Not Yet Fully Implemented:** Event types ending in `.removed` (e.g. `vehicle.removed`, `user.removed`) are listed in the webhook event catalog but are not reliably fired yet. Do not build logic that depends on these events — use the REST API to detect deletions for now. We will communicate when `.removed` events are fully supported.
</Warning>

***

## Endpoint Requirements

Your webhook endpoint must meet these requirements for successful event delivery:

<CardGroup cols={2}>
  <Card icon="lock" title="HTTPS Required">
    Endpoints must use HTTPS with a valid SSL certificate. HTTP is not supported.
  </Card>

  <Card icon="stopwatch" title="Fast Response">
    Return a `202 Accepted` response within **3 seconds**. Any non-`5xx` status code indicates successful delivery.
  </Card>

  <Card icon="shield-check" title="Signature Validation">
    Verify webhook signatures using HMAC-SHA256 to ensure requests are authentic and haven't been tampered with.
  </Card>

  <Card icon="code" title="Async Processing">
    Acknowledge receipt immediately and process event data in the background to avoid timeouts and ensure reliability.
  </Card>
</CardGroup>

<Info>
  **IP Whitelisting:** If your infrastructure requires IP whitelisting for additional security, [contact our support team](mailto:support@catenatelematics.com) to receive the list of webhook delivery IPs.
</Info>

***

## Ready to Get Started?

<CardGroup cols={2}>
  <Card title="Webhook Quick Start" icon="bolt" href="/api-reference/webhooks/webhook-setup">
    Set up your first webhook subscription and start receiving live fleet events in under 15 minutes.
  </Card>

  <Card title="Security & Validation" icon="shield-check" href="/api-reference/webhooks/webhook-validation">
    Learn how to verify webhook signatures and secure your endpoint.
  </Card>

  <Card title="Operations & Monitoring" icon="chart-line" href="/api-reference/webhooks/operations-monitoring">
    Monitor delivery health, replay failed events, and manage the webhook lifecycle.
  </Card>

  <Card title="FAQ" icon="circle-question" href="/api-reference/webhooks/webhook-faq">
    Answers to common questions about webhook behavior and troubleshooting.
  </Card>
</CardGroup>