> 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. # Frequently Asked Questions #### How do I filter data by specific fleets? 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. #### What happens if a fleet disconnects their provider? 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. #### How often is data updated? 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. #### How quickly are webhook events delivered after data changes? 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](/get-started/writing-data) for details on async vs. sync modes. #### Can a fleet connect multiple telematics providers? Yes! Fleets can connect multiple TSPs, and Catena will aggregate and normalize data from all connected sources. #### Should I use fleet_ref or connection_id in my integration? 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](/recipes/filtering-requests#fleet-identifiers) for a detailed explanation. #### What webhook events are triggered when a fleet is invited and onboards? The full lifecycle sequence is: `invitation.created` → `invitation.viewed` → `invitation.accepted` (or `invitation.declined`) → `share_agreement.created` → `connection.created` → `fleet_connection.created`. 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](/recipes/create-invitations) for the complete flowchart and setup instructions. #### How do I detect stale or invalid TSP credentials? Catena automatically detects when a fleet's TSP credentials become invalid and emits a `connection.staled` event. Subscribe to this event via [webhooks](/api-reference/notifications/webhooks/overview) 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](/recipes/create-invitations#operational-events) for the full list of connection health events. #### Can I replay missed webhooks if my endpoint had a bug or outage? 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 > **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. Reactivate paused webhooks as soon as possible to minimize gaps. See [Operations & Monitoring — Event Replay](/api-reference/notifications/webhooks/operations-monitoring#event-replay) for full details. #### Can Catena automatically reactivate a paused webhook? 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. > **Warning** > > 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](/api-reference/notifications/webhooks/operations-monitoring#circuit-breaker) for details. --- #### [Contact Support](mailto:support@catenaclearing.io) Have questions or need assistance? Our team is here to help you succeed.