Skip to main content
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.

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

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

​
Ready to Get Started?

Webhook Quick Start

Set up your first webhook subscription and start receiving live fleet events in under 15 minutes.

Security & Validation

Learn how to verify webhook signatures and secure your endpoint.

Operations & Monitoring

Monitor delivery health, replay failed events, and manage the webhook lifecycle.

FAQ

Answers to common questions about webhook behavior and troubleshooting.