How do I set up webhooks?
Set up Catena webhooks with secure delivery and signature verification.
Setting up a webhook takes four steps:
- Create an HTTPS endpoint on your server that accepts POST requests and returns a 202 Accepted response within 3 seconds. Acknowledge receipt immediately and process the event asynchronously in the background.
- Call POST /v2/notifications/webhooks with your endpoint URL and the event_name you want to subscribe to (for example, vehicle_location.added or invitation.*). The response includes a webhook ID and a secret.
- Save the secret immediately. It is shown in full only once. Store it in your secrets manager, as it is needed to verify incoming requests.
- Verify the HMAC-SHA256 signature on every incoming webhook. Each request includes an X-Catena-Signature header and an X-Catena-Timestamp header. Verify them before processing any event to confirm the request is genuinely from Catena.
Webhook payloads are gzip-compressed. Your endpoint must decompress the body before parsing it. Each payload contains a data array even when only one record is included.
The recommended approach is to create one subscription per event type without filters. This covers all of your carriers automatically, including ones you onboard in the future. Use the fleet_ref field in each event payload to route events to the correct carrier in your system.