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.
2. Click Create Webhook Endpoint.
3. Enter your HTTPS endpoint URL.
4. Choose the events you want to receive.
5. 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 200, 201, 202, or 204 after it accepts the event.

app.post("/webhooks/terminal49", express.raw({ type: "application/json" }), (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.