Async Write Operations

Asynchronous mode is the default processing mode for all write operations. When you submit a request, Catena immediately returns a 202 Accepted response with a resource operation ID, then processes the request in the background with automatic retries and rate limiting.

Best for production workloads where you want to create or update multiple resources without waiting for each TSP response. Catena handles retries, rate limiting, and error recovery automatically.

How It Works

You submit a write request

Send a POST or PATCH request to the Telematics API with is_sync=false (or omit the parameter, since async is the default).

Catena returns immediately

You receive a 202 Accepted response containing a resource operation object with status: "pending". The id field is the operation tracking ID.

Catena processes in the background

The request is queued and processed with automatic retries and rate limiting to respect TSP API limits.

You receive the result via webhook

Catena sends a resource_operation.succeeded or resource_operation.failed webhook event with the final status and details.

Example: Sending a Message

Request

cURL

curl -X POST 'https://api.catenatelematics.com/v2/telematics/messages' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
    "sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
    "recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
    "message_text": "Delivery confirmed at warehouse B",
    "priority": "low",
    "partner_ref": "dispatch-msg-8812"
  }'

The sender_id and recipient_id are Catena user IDs. Catena automatically resolves them to the TSP-specific identifiers (e.g., source_sender_id, source_recipient_id) before forwarding the request.partner_ref is optional. It is your own reference for this message, and Catena returns it trimmed (leading and trailing whitespace removed) on the operation and its webhooks. See Your Own Reference.

Response (202 Accepted)

{
  "id": "019df228-725e-7568-aaa8-d0029dffb003",
  "created_at": "2026-05-04T08:43:50.238535Z",
  "updated_at": "2026-05-04T08:43:50.238540Z",
  "deleted_at": null,
  "partner_id": "9df92c50-d8a7-460e-aab2-a93f1de9280a",
  "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
  "partner_ref": "dispatch-msg-8812",
  "resource": "message",
  "resource_id": null,
  "source_id": null,
  "operation_type": "create",
  "payload": {
    "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
    "sender_id": "f9c7ee1c-2e16-5858-9b7e-ff7c89a4dd04",
    "recipient_id": "b224f322-b3d2-57e0-b245-cda313f68a1d",
    "message_text": "Delivery confirmed at warehouse B",
    "priority": "low",
    "partner_ref": "dispatch-msg-8812",
    "reply_to_message_id": null,
    "source_sender_id": "51477344",
    "source_recipient_id": "51477717",
    "source_reply_to_message_id": null
  },
  "status": "pending",
  "logs": []
}

Key fields in the response:

Field	Description
`id`	The resource operation ID. Use this to track the operation status.
`status`	Always `"pending"` for async operations at creation time.
`resource`	The type of resource being created (e.g., `message`, `vehicle`).
`operation_type`	Either `"create"` or `"update"`.
`partner_ref`	The reference you sent in the request, returned trimmed (leading and trailing whitespace removed). `null` if you didn’t send one.
`resource_id`	The Catena ID of the created resource. `null` until the operation succeeds.
`source_id`	The TSP-side ID of the created resource. `null` until the operation succeeds.
`payload`	The full payload sent to the TSP, including auto-resolved source IDs.
`logs`	Empty initially. Populated with attempt logs if the operation fails.

Notice how the payload contains both your Catena IDs (sender_id, recipient_id) and the automatically resolved TSP IDs (source_sender_id, source_recipient_id). You don’t need to look these up yourself.

Receiving Results via Webhooks

To know whether an async operation succeeded or failed, subscribe to resource operation webhook events. Create a webhook subscription for resource operation events:

cURL

curl -X POST 'https://api.catenatelematics.com/v2/notifications/webhooks' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://your-domain.com/webhooks/catena",
    "event_name": "resource_operation.*",
    "secret": "your-webhook-secret-min-12-chars"
  }'

Using resource_operation.* subscribes you to all three events: created, succeeded, and failed. You can also subscribe to individual events if you only need specific notifications.

Success Webhook Payload

When the operation succeeds, the resource_operation.succeeded event includes the resource_id (Catena ID) and source_id (TSP ID) of the created resource, along with the partner_ref you sent:

{
  "version": "1.0",
  "event_name": "resource_operation.succeeded",
  "webhook_id": "...",
  "timestamp": "2026-05-04T08:43:55.000Z",
  "data": [
    {
      "id": "019df228-725e-7568-aaa8-d0029dffb003",
      "status": "success",
      "resource": "message",
      "resource_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source_id": "98765432",
      "operation_type": "create",
      "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
      "partner_ref": "dispatch-msg-8812",
      "payload": { "..." },
      "logs": []
    }
  ]
}

Failure Webhook Payload

When the operation fails, the event includes error logs with details about what went wrong:

{
  "version": "1.0",
  "event_name": "resource_operation.failed",
  "webhook_id": "...",
  "timestamp": "2026-05-04T08:43:55.000Z",
  "data": [
    {
      "id": "019df228-725e-7568-aaa8-d0029dffb003",
      "status": "failed",
      "resource": "message",
      "resource_id": null,
      "source_id": null,
      "operation_type": "create",
      "connection_id": "019ddd87-eedd-710f-967c-1c6cc72ac985",
      "partner_ref": "dispatch-msg-8812",
      "payload": { "..." },
      "logs": [
        {
          "id": "019df22f-093f-7949-908d-d5564941fdbe",
          "created_at": "2026-05-04T08:51:02.079501Z",
          "resource_operation_id": "019df228-725e-7568-aaa8-d0029dffb003",
          "status": "failed",
          "error_type": "auth",
          "error_details": "Client error '401 Unauthorized' for url '...'"
        }
      ]
    }
  ]
}

Error types you may encounter:

Error Type	Description
`auth`	Authentication failed with the TSP (e.g., expired credentials)
`validation`	The TSP rejected the payload (e.g., missing required fields)
`network`	Network error connecting to the TSP
`tsp`	The TSP returned an unexpected error

Matching Results to Your Records

If you save a record in your own system before you call Catena, send that record’s ID as partner_ref. Every resource operation event for that write then carries a key that already means something in your system.

Save your record and send its ID

Create the record in your system, then call POST /v2/telematics/messages (or POST /v2/telematics/group-messages) with "partner_ref": "<your record ID>". Store the resource operation id from the 202 response on your record.

Handle resource_operation.succeeded

Find your record by the operation id. If you haven’t stored it yet, for example because the webhook arrived before your code finished saving the 202 response, fall back to partner_ref. Then store the event’s resource_id. The event’s resource field tells you what that ID identifies:

`resource`	`resource_id` is	Where you’ll see the same ID
`message`	A message ID	`GET /v2/telematics/messages` and `message.*` webhooks
`group_message`	A group message ID	`GET /v2/telematics/group-messages` and `group_message.*` webhooks

Handle resource_operation.failed

Find your record the same way and mark it as not delivered. The logs array explains why.

Why not look up by partner_ref alone? Catena does not enforce uniqueness on it, so a reused value, for example after a retry, can match more than one of your records. The resource operation id is unique. Use partner_ref as the key that is meaningful in your system and as a fallback, not as the only match.

Python

def find_record(operation: dict):
    # The operation id is unique; partner_ref is not, so it is only a fallback.
    record = my_records.find_by_operation_id(operation["id"])
    if record is None and operation.get("partner_ref") is not None:
        candidates = my_records.find_pending(
            partner_ref=operation["partner_ref"], kind=operation["resource"]
        )
        if len(candidates) == 1:
            record = candidates[0]
            record.operation_id = operation["id"]
    return record


def handle_resource_operation_event(event: dict) -> None:
    for operation in event["data"]:
        if operation["resource"] not in ("message", "group_message"):
            continue

        record = find_record(operation)
        if record is None:
            continue  # not a write you tracked, or an ambiguous ref to review by hand

        if event["event_name"] == "resource_operation.succeeded":
            if operation["resource"] == "message":
                record.catena_message_id = operation["resource_id"]
            else:
                record.catena_group_message_id = operation["resource_id"]
            record.status = "sent"
        elif event["event_name"] == "resource_operation.failed":
            record.status = "failed"
            record.error = operation["logs"][-1]["error_details"] if operation["logs"] else None
        record.save()

Polling for Status

If you prefer not to use webhooks, you can poll the operation status using the Integrations API:

cURL

curl -X GET 'https://api.catenatelematics.com/v2/integrations/connections/019ddd87-eedd-710f-967c-1c6cc72ac985/resource-operations/019df228-725e-7568-aaa8-d0029dffb003' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Or list all recent operations with filtering:

cURL

curl -X GET 'https://api.catenatelematics.com/v2/integrations/connections/resource-operations?connection_id=019ddd87-eedd-710f-967c-1c6cc72ac985&resource=message' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Webhooks are the recommended approach for tracking async operations. Polling introduces latency and unnecessary API calls. Reserve polling for debugging or one-off status checks.

When to Use Async Mode

Bulk operations

When creating or updating many resources at once (e.g., sending messages to an entire fleet), async mode lets you fire requests rapidly without waiting for each TSP response.

Non-blocking workflows

When your application doesn’t need to wait for the TSP’s response to continue its workflow. For example, dispatching a message where delivery confirmation can arrive later.

Production workloads

Async mode provides built-in retries and rate limiting, making it more resilient for production use. Catena manages the complexity of TSP-specific rate limits and transient failures.

You must implement webhook handling to catch failed operations. Without it, you won’t know if a request failed on the TSP side. Build controls to listen for resource_operation.failed events and resolve issues (e.g., invalid credentials, missing required fields).

Next Steps

Sync Operations

Learn about synchronous mode for immediate TSP feedback.

Get Started

Freight Concepts

Legal Information

How It Works

Example: Sending a Message

Request

Response (202 Accepted)

Receiving Results via Webhooks

Success Webhook Payload

Failure Webhook Payload

Matching Results to Your Records

Polling for Status

When to Use Async Mode

Next Steps

Sync Operations

​How It Works

​Example: Sending a Message

​Request

​Response (202 Accepted)

​Receiving Results via Webhooks

​Subscribe to Events

​Success Webhook Payload

​Failure Webhook Payload

​Matching Results to Your Records

​Polling for Status

​When to Use Async Mode

​Next Steps

Sync Operations

How It Works

Example: Sending a Message

Request

Response (202 Accepted)

Receiving Results via Webhooks

Subscribe to Events

Success Webhook Payload

Failure Webhook Payload

Matching Results to Your Records

Polling for Status

When to Use Async Mode

Next Steps