Skip to main content

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.

Setting up webhooks with Catena is straightforward: create a secure HTTPS endpoint, subscribe to events through the API, and start receiving real-time notifications instantly.
Available Events: View the complete list of webhook events and their payloads in the API Reference.

​
Setup Process

Create Your Webhook Endpoint

Set up a secure HTTPS endpoint on your server to receive webhook notifications. Your endpoint should accept POST requests and return a 202 Accepted response within 3 seconds.
Example Endpoint
POST https://your-domain.com/webhooks/catena
Quick Start: Use services like webhook.site or RequestBin to test webhook delivery before implementing your production endpoint.

Subscribe to Events

Use the Notifications API to create a webhook subscription for specific events. Include your endpoint URL, optional filters, and a signing secret.See the Notifications API Reference for complete endpoint documentation and code examples.
Store Your Secret Safely: If you don’t provide a secret, Catena generates one automatically and returns it only once during subscription creation. Store it securely—you won’t be able to retrieve it again.

Handle Incoming Events

Process webhook notifications at your endpoint. Each event includes a JSON payload with event data and verification headers.
Success Response: Always return 202 Accepted to acknowledge receipt. Any non-5xx status code indicates successful delivery.

Verify and Process

Validate the webhook signature to ensure the request is authentic, then process the event data asynchronously.See Webhook Validation for signature verification implementation.
Unique Subscriptions: You can only create one subscription per unique combination of event type, endpoint URL, and filters. To send the same events to multiple endpoints, create separate subscriptions with different URLs.

​
Event Filtering

Use filters to scope webhook delivery to specific fleets, reducing unnecessary notifications and processing overhead:
Receive events only for specific fleets using Catena’s internal fleet IDs.
{
  "filters": {
    "fleet_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
  }
}
Target events for fleets using your custom fleet references (the ID of the fleet in your system).
{
  "filters": {
    "fleet_refs": ["ACME-FLEET-001", "ACME-FLEET-002"]
  }
}
Use both fleet IDs and fleet references together. Filters use OR logic—events matching either criteria will be delivered.
{
  "filters": {
    "fleet_ids": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "fleet_refs": ["ACME-FLEET-001"]
  }
}
Omit Filters to Receive All Events: If you don’t specify any filters, you’ll receive all events of the subscribed type across your entire organization.

​
Single Webhook for All Fleets

You can register one master webhook subscription to receive events for all authorized fleets in your organization, rather than creating separate webhooks per fleet. This simplifies webhook management for partners handling multiple fleet customers.
1

Create One Subscription

Subscribe to an event type (e.g., vehicle.modified) without filters to receive events from all fleets.
2

Identify the Fleet

Each event payload includes a fleet_id field that identifies which fleet the event belongs to.
3

Map to Your System

Use the Share Agreements API to retrieve the mapping between Catena’s fleet_id and your internal customer identifiers (fleet_ref) to route events correctly.
Event Payloads Do Not Include fleet_ref: Webhook event payloads contain fleet_id (Catena’s internal identifier) but not your custom fleet_ref. Use the Organizations API to query share agreements and map fleet_id to your fleet_ref for customer identification.
Alternative Approach: If you prefer, you can create multiple webhook subscriptions with different fleet_refs filters to route events to different endpoints based on customer segments.