Receive Shipment Status Updates with Webhooks

Set up Terminal49 webhooks to receive real-time shipment and container status updates, including milestone events, whenever tracking data changes.

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:

1. Open Developer Webhooks

   Go to Developer Webhooks in your Terminal49 dashboard.

2. Create the endpoint

   Click Create Webhook Endpoint and enter your HTTPS endpoint URL.

3. 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:

1. Verify the X-T49-Webhook-Signature header against the raw request body.
2. Allowlist Terminal49 webhook IPs.
3. Deduplicate by data.id.
4. 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.

Next steps

Event catalog

Choose the events your integration should subscribe to.

Payload reference

Review the notification envelope and example payloads.