Webhooks FAQ - Catena Telematics API

Why isn't my webhook firing for .removed events?

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.

Why did my webhook stop delivering events?

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:

    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 for more detail.

I lost my signing secret. How do I recover it?

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:

    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.

Will I get .added events for entities that already exist when a fleet connects?

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:

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.
Use webhooks for ongoing changes — Once you have the initial snapshot, rely on webhooks to receive incremental updates.

Do webhooks fire retroactively when I create a new subscription?

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.

What's the difference between fleet_id and fleet_ref in the payload?

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.

Why are events arriving out of order?

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.

How do I know if my webhook is healthy?

Two good signals to monitor:

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

    curl --url https://api.catenatelematics.com/v2/notifications/webhooks/<webhook_id>/metrics \
      -H 'Authorization: Bearer <token>'

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 for the full monitoring reference.

Are there limits on how many webhooks I can create or how many events can be delivered?

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 to confirm the limits that apply to your account.

Contact Support