Receive Shipment Status Updates with Webhooks

In this tutorial, you will register a webhook endpoint and confirm the shape of the status updates Terminal49 sends. Use webhooks for ongoing tracking updates. Polling is useful for on-demand lookups, but it adds latency and consumes API rate limits.

Before you start

You need:

A Terminal49 API key.
A public HTTPS endpoint that can receive POST requests.
At least one active tracking request.

For local testing, use a temporary endpoint from a tool such as webhook.site. For production, use an endpoint in your own application.

Create a webhook endpoint

You can create a webhook from the dashboard or the API. To use the dashboard:

Open Developer Webhooks

Go to Developer Webhooks in your Terminal49 dashboard.

Create the endpoint

Click Create Webhook Endpoint and enter your HTTPS endpoint URL.

Choose events and save

Choose the events you want to receive, then save the webhook.

To use the API, send:

curl -X POST "https://api.terminal49.com/v2/webhooks" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "webhook",
      "attributes": {
        "url": "https://example.com/webhooks/terminal49",
        "active": true,
        "events": ["tracking_request.succeeded", "container.updated"]
      }
    }
  }'

The response includes the webhook id and secret. Store the secret securely; you use it to verify webhook signatures.

Receive the first event

After Terminal49 detects a change for one of your tracked shipments or containers, it sends a POST request to your endpoint. Every notification has the same top-level shape:

{
  "data": {
    "id": "87d4f5e3-df7b-4725-85a3-b80acc572e5d",
    "type": "webhook_notification",
    "attributes": {
      "event": "tracking_request.succeeded",
      "delivery_status": "pending",
      "created_at": "2026-05-11T18:30:00Z"
    }
  },
  "included": []
}

Check data.attributes.event first. This tells your handler which code path to run. Common first events are:

tracking_request.succeeded: Terminal49 found the shipment and created tracking records.
tracking_request.failed: Terminal49 could not create tracking for the submitted number.
container.updated: One or more container attributes changed.

Return a successful response

Your endpoint should return a success status (200, 201, 202, or 204) after it durably accepts the event — persist or enqueue the payload first, then process it asynchronously.

app.post("/webhooks/terminal49", express.raw({ type: "*/*" }), (req, res) => {
  const payload = JSON.parse(req.body.toString("utf8"));

  queueWebhookForProcessing(payload);

  res.sendStatus(202);
});

If Terminal49 receives another response code or the request times out, it retries the notification.

Before you use webhooks in production

Production webhook handlers should:

Verify the X-T49-Webhook-Signature header against the raw request body.
Allowlist Terminal49 webhook IPs.
Deduplicate by data.id.
Process asynchronously when work may take more than a few seconds.

Follow Setting up webhooks for signature examples and Webhook Best Practices for retry handling.

Getting Started

Tracking Fundamentals

Webhooks & Events

Integrations & Embeds

Platform & Reference

Receive Shipment Status Updates with Webhooks

Before you start

Create a webhook endpoint

Receive the first event

Return a successful response

Before you use webhooks in production

Next steps

Event catalog

Payload reference

​Before you start

​Create a webhook endpoint

​Receive the first event

​Return a successful response

​Before you use webhooks in production

​Next steps

Event catalog

Payload reference

Before you start

Create a webhook endpoint

Receive the first event

Return a successful response

Before you use webhooks in production

Next steps