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

# Frequently Asked Questions

> Answers to common questions about integrating with the Catena Telematics API

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Can a fleet connect multiple telematics providers?">
    Yes! Fleets can connect multiple TSPs, and Catena will aggregate and normalize data from all connected sources.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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/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.
  </Accordion>

  <Accordion title="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.
    </Warning>

    See [Operations & Monitoring — Event Replay](/api-reference/webhooks/operations-monitoring#event-replay) for full details.
  </Accordion>

  <Accordion title="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.
    </Warning>

    See [Operations & Monitoring](/api-reference/webhooks/operations-monitoring#circuit-breaker) for details.
  </Accordion>
</AccordionGroup>

***

<Card icon="life-ring" title="Contact Support" href="mailto:support@catenaclearing.io">
  Have questions or need assistance? Our team is here to help you succeed.
</Card>