Skip to main content
Use query parameters like fleet_ids or fleet_refs in your API requests to filter results. Check the API reference for each endpoint’s available filters.
You’ll receive a webhook notification (if configured), and the fleet’s status will update. Historical data remains accessible, but new data will stop flowing.
Ingestion frequency varies by resource type and telematics provider. Location data is typically ingested every minute, while metadata (vehicles, drivers) updates less frequently.To check the exact frequency for a specific fleet, query the List Schedules endpoint filtered by connection_id. Each schedule shows the resource type and polling interval for that connection.Catena automatically handles retries and rate limiting against TSP APIs during ingestion — you don’t need to manage this yourself.
Webhook events are typically delivered within 200–500 ms of the triggering event. For example, if vehicle locations are ingested every minute, you’ll receive a vehicle_location.added webhook within 500 ms of each ingestion.For write operations (resource operations), the delivery timing depends on the processing mode:
  • Async mode (default): Catena handles retries and rate limiting automatically. You receive a resource_operation.succeeded or resource_operation.failed webhook when processing completes.
  • Sync mode: The TSP response is returned directly in your HTTP call. No webhook is fired.
See Writing Data to TSPs for details on async vs. sync modes.
Yes! Fleets can connect multiple TSPs, and Catena will aggregate and normalize data from all connected sources.
It depends on whether you are reading or writing data:
  • Reading: Use fleet_refs to query data. Catena returns results from all TSPs the fleet is connected to.
  • Writing: Use connection_id to specify which TSP should receive the request. Catena cannot send a write to all providers at once.
To find the connection_id for a fleet, either query the List Connections endpoint filtered by fleet_refs, or read it from an existing resource’s response (every resource includes a connection_id field).See Filter & Query Data for a detailed explanation.
The full lifecycle sequence is: invitation.created → invitation.viewed → invitation.accepted (or invitation.declined) → share_agreement.created → connection.created → fleet_connection.created.connection.created is skipped when Catena reuses an existing connection (for example, when the fleet uses the same TSP credentials as another fleet). In that case only fleet_connection.created fires, so treat it as the signal that onboarding is complete.You can receive these automatically by either:
  1. Setting webhooks for each event (ie. invitation.*, share_agreement.*, connection.*, fleet_connection.*). This will return all events regarless of the fleet.
  2. Setting the callback_url when creating the invitation. This will automatically create webhooks filtered by the specific fleet. Keep callback_url empty to avoid duplicated events if you implement the first approach.
See Inviting Fleets for the complete flowchart and setup instructions.
Catena automatically detects when a fleet’s TSP credentials become invalid and emits a connection.staled event. Subscribe to this event via webhooks to get notified immediately — no polling required.When a connection goes stale:
  • Catena stops fetching data for that connection
  • The fleet must re-authenticate using the same invitation link to restore the connection
  • Once re-authenticated, data ingestion resumes automatically
You can also query the List Connections endpoint and check the status field to find stale connections.See Inviting Fleets — Operational Events for the full list of connection health events.
Catena maps both fleets to the same connection. A connection represents one set of TSP credentials, so a second fleet that authenticates with identical credentials is linked to the existing connection instead of creating a new one.In practice this means:
  • Both fleets share the same connection_id
  • Only the first fleet triggers connection.created; later fleets reuse the connection and receive only their own fleet_connection.created event
  • If the credentials become invalid, the shared connection goes stale and data stops flowing for both fleets
  • Because there is only one connection, re-authenticating it restores data ingestion for every fleet mapped to it
See Platform Concepts — Connection for more on how connections work.
Yes — but only for events that Catena attempted to deliver and failed. These are stored in the Dead Letter Queue (DLQ) for up to 14 days. After fixing the issue on your side, call the Replay Undelivered Messages endpoint to redeliver all queued events.The process is:
  1. Fix the bug or restore your endpoint
  2. Call the replay endpoint for the affected webhook subscription
  3. Monitor delivery to confirm events are processing successfully
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. Reactivate paused webhooks as soon as possible to minimize gaps.
See Operations & Monitoring — Event Replay for full details.
No. Catena’s circuit breaker automatically pauses webhooks when the delivery success rate drops below acceptable thresholds, but it does not auto-reactivate them — only you know when the underlying issue has been resolved.To monitor for paused webhooks:
  • Subscribe to the webhook.staled event to get notified immediately
  • Query the List Webhook Subscriptions endpoint filtered by status=stale
After fixing the issue, call the Activate Webhook Subscription endpoint to resume delivery.
Events that occur while a webhook is paused are not queued. Reactivate as soon as possible to minimize gaps in event delivery.
See Operations & Monitoring for details.

Contact Support

Have questions or need assistance? Our team is here to help you succeed.