Skip to main content

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

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.

​
Key Features

Subscribe to 50+ event types covering fleet telematics (vehicles, drivers, locations), compliance (HOS, IFTA), organizational changes (invitations, share agreements, connections), and system operations (webhooks, executions, schedules).
Use wildcard patterns like vehicle.* to subscribe to all events for a resource (added, modified, removed), simplifying webhook management for comprehensive monitoring.
Filter webhook deliveries by fleet IDs or fleet references to receive only relevant events for specific customers or business segments.
Track webhook health with 8 metrics across 4 time windows (6h, 24h, 7d, 14d): HTTP attempts, success rates, response times, message counts, and dead letter queue depth.
Automatic retries with exponential backoff, dead letter queue (14-day retention), circuit breaker for unhealthy endpoints, HMAC-SHA256 signature verification, and message replay capability.
Access complete OpenAPI 3.0 schemas for each event type with version tracking and changelogs to ensure compatibility as event structures evolve.

​
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 timestamp field in the event payload to determine the correct chronological sequence.
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.
Webhooks with consistently low success rates are automatically marked as stale and paused to prevent wasted resources. You must manually reactivate the subscription after resolving the underlying issues.

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