> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://catena.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server. # Webhooks Overview 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. --- ## How Webhooks Work #### Event Occurs An event (like `vehicle.modified` or `hos_violation.added`) happens within the Catena platform. #### Catena Sends Notification 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. #### Your System Acknowledges Your endpoint receives the event and returns a `202 Accepted` response within 3 seconds to confirm receipt. #### Process the Event Your application processes the event data asynchronously—updating records, triggering workflows, or notifying users. > **Tip** > > **Best Practice:** Return `202 Accepted` immediately, then queue the event for background processing. This prevents timeouts and ensures reliable delivery. --- ## 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: #### At-Least-Once Delivery 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. #### Automatic Retries 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. #### Out-of-Order Delivery 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. #### Dead Letter Queue (DLQ) 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. #### Circuit Breaker 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/notifications/webhooks/operations-monitoring#circuit-breaker) for full details on monitoring, reactivation, and recovery. > **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. --- ## Endpoint Requirements Your webhook endpoint must meet these requirements for successful event delivery: #### HTTPS Required Endpoints must use HTTPS with a valid SSL certificate. HTTP is not supported. #### Fast Response Return a `202 Accepted` response within **3 seconds**. Any non-`5xx` status code indicates successful delivery. #### Signature Validation Verify webhook signatures using HMAC-SHA256 to ensure requests are authentic and haven't been tampered with. #### Async Processing Acknowledge receipt immediately and process event data in the background to avoid timeouts and ensure reliability. > **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. --- ## Ready to Get Started? #### [Webhook Quick Start](/api-reference/notifications/webhooks/webhook-setup) Set up your first webhook subscription and start receiving live fleet events in under 15 minutes. #### [Security & Validation](/api-reference/notifications/webhooks/webhook-validation) Learn how to verify webhook signatures and secure your endpoint. #### [Operations & Monitoring](/api-reference/notifications/webhooks/operations-monitoring) Monitor delivery health, replay failed events, and manage the webhook lifecycle. #### [FAQ](/api-reference/notifications/webhooks/webhook-faq) Answers to common questions about webhook behavior and troubleshooting.