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.
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.
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.
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.
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 for full details on monitoring, reactivation, and recovery.
.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:
IP Whitelisting: If your infrastructure requires IP whitelisting for additional security, contact our support team to receive the list of webhook delivery IPs.