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

> Answers to common questions about Catena webhooks

Answers to the questions that come up most often when building webhook integrations with Catena.

***

<AccordionGroup>
  <Accordion title="Why isn't my webhook firing for .removed events?" icon="circle-xmark">
    Event types ending in `.removed` (e.g. `vehicle.removed`, `user.removed`) are listed in the webhook event catalog but are **not yet fully implemented**. They will not reliably fire when a record is deleted or deactivated at the TSP.

    In the meantime, use the REST API to detect deletions by checking for records where `deleted_at` is populated. We will communicate when `.removed` events are fully supported.
  </Accordion>

  <Accordion title="Why did my webhook stop delivering events?" icon="bolt-slash">
    Catena has a circuit breaker that automatically pauses webhooks when the delivery success rate drops below acceptable thresholds. When this happens, your webhook status changes to `stale`.

    Common causes are an endpoint that isn't responding within 3 seconds, returning `5xx` errors, or being unreachable. Check your delivery logs for error patterns, fix the underlying issue, then reactivate:

    ```bash theme={null}
        curl -X POST \
          --url https://api.catenatelematics.com/v2/notifications/webhooks/<webhook_id>/activate \
          -H 'Authorization: Bearer <token>'
    ```

    You can also subscribe to `webhook.staled` events to be notified automatically when the circuit breaker trips.

    See [Operations & Monitoring](/api-reference/webhooks/operations-monitoring) for more detail.
  </Accordion>

  <Accordion title="I lost my signing secret. How do I recover it?" icon="key">
    You can't retrieve a lost secret — it's masked as `*****` in all API responses after creation. To recover, rotate to a new secret using the update endpoint:

    ```bash theme={null}
        curl -X PATCH \
          --url https://api.catenatelematics.com/v2/notifications/webhooks/<webhook_id> \
          -H 'Authorization: Bearer <token>' \
          -H 'Content-Type: application/json' \
          -d '{"secret": "your-new-secret-min-12-chars"}'
    ```

    Update your endpoint to use the new secret immediately — deliveries will begin failing signature verification as soon as the rotation takes effect.
  </Accordion>

  <Accordion title="Will I get .added events for entities that already exist when a fleet connects?" icon="truck">
    Not necessarily. `*.added` events only fire for entities Catena hasn't seen before. If a vehicle or driver already exists in Catena from a previous connection — either from the same fleet via a different TSP, or from another partner — the `*.added` event will not fire again when a new fleet connects.

    This means you should not rely solely on webhooks to build your initial data set. The recommended pattern is:

    1. **Backfill on connection** — When you receive a `share_agreement.created` or `connection.created` event, immediately query the REST API to fetch the current state of all vehicles, drivers, and other entities for that fleet.
    2. **Use webhooks for ongoing changes** — Once you have the initial snapshot, rely on webhooks to receive incremental updates.
  </Accordion>

  <Accordion title="Do webhooks fire retroactively when I create a new subscription?" icon="clock-rotate-left">
    No. Webhooks only deliver events that occur after the subscription is created. Historical data is not replayed when you subscribe.

    To get data that existed before your subscription, query the relevant REST API endpoints. Once you have that initial snapshot, your webhook subscription will keep it up to date going forward.
  </Accordion>

  <Accordion title="What's the difference between fleet_id and fleet_ref in the payload?" icon="tag">
    Both fields identify the fleet an event belongs to, but they come from different sources:

    * **`fleet_id`** — Catena's internal UUID for the fleet. Consistent across all events but not meaningful in your own system.
    * **`fleet_ref`** — Your own identifier for the fleet, set when you created the invitation. Use this to route events to the right customer in your system without a separate API lookup.

    If you didn't set a `fleet_ref` when creating the invitation, you can map `fleet_id` to your internal identifiers by querying the [Organizations API](/api-reference/organizations-api).
  </Accordion>

  <Accordion title="Why are events arriving out of order?" icon="shuffle">
    Catena uses an at-least-once delivery model, and retries combined with network conditions can cause events to arrive out of sequence. Never rely on delivery order to determine what happened first.

    Always use the `occurred_at` field inside the event `data` payload — not the outer `timestamp` or delivery time — to establish the correct chronological sequence of events.
  </Accordion>

  <Accordion title="How do I know if my webhook is healthy?" icon="chart-line">
    Two good signals to monitor:

    1. **Metrics endpoint** — Returns success rates, failure counts, response times, and DLQ depth across four rolling windows (6h, 24h, 7d, 14d):

    ```bash theme={null}
        curl --url https://api.catenatelematics.com/v2/notifications/webhooks/<webhook_id>/metrics \
          -H 'Authorization: Bearer <token>'
    ```

    2. **`webhook.staled` event** — Subscribe to this event to receive an immediate notification if the circuit breaker trips and your webhook is paused.

    See [Operations & Monitoring](/api-reference/webhooks/operations-monitoring) for the full monitoring reference.
  </Accordion>

  <Accordion title="Are there limits on how many webhooks I can create or how many events can be delivered?" icon="gauge-high">
    Catena enforces limits on both the number of webhook subscriptions per account and the rate of event delivery. Current limits are not published in this documentation as they may vary by plan and are subject to change.

    Contact [support@catenaclearing.io](mailto:support@catenaclearing.io) to confirm the limits that apply to your account.
  </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>