> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Payloads

> Reference the Terminal49 webhook notification envelope, included resource patterns, and links to complete event payload examples.

Every Terminal49 webhook delivery is a JSON:API document with a `webhook_notification` primary resource and related records in `included`.

Use this page as the payload reference. Use [Payload Examples](/api-docs/useful-info/webhook-events-examples) when you need complete sample JSON.

## Notification envelope

```json theme={null}
{
  "data": {
    "id": "87d4f5e3-df7b-4725-85a3-b80acc572e5d",
    "type": "webhook_notification",
    "attributes": {
      "event": "container.updated",
      "delivery_status": "pending",
      "created_at": "2026-05-11T18:30:00Z"
    },
    "relationships": {
      "webhook": {
        "data": {
          "id": "8a5ffa8f-3dc1-48de-a0ea-09fc4f2cd96f",
          "type": "webhook"
        }
      },
      "reference_object": {
        "data": {
          "id": "e8f1976c-0089-4b98-96ae-90aa87fbdfee",
          "type": "container_updated_event"
        }
      }
    }
  },
  "included": []
}
```

## Top-level fields

| Field                                 | Type         | Description                                                                                |
| ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| `data.id`                             | UUID         | Unique webhook notification ID. Use this as the idempotency key.                           |
| `data.type`                           | string       | Always `webhook_notification`.                                                             |
| `data.attributes.event`               | string       | Event name, such as `tracking_request.succeeded` or `container.updated`.                   |
| `data.attributes.delivery_status`     | string       | Delivery state for this notification. Values include `pending`, `succeeded`, and `failed`. |
| `data.attributes.created_at`          | timestamp    | Time Terminal49 created the notification.                                                  |
| `data.relationships.webhook`          | relationship | Webhook endpoint that received the notification.                                           |
| `data.relationships.reference_object` | relationship | Event-specific object that caused the notification.                                        |
| `included`                            | array        | Related records included for convenience. Contents vary by event.                          |

## Reference object types

| Event family                                                                                                  | Common `reference_object.type`  | Notes                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tracking_request.*`                                                                                          | `tracking_request`              | Includes the tracking request and, when available, shipment/container records.                                                                                                       |
| `container.transport.*`                                                                                       | `transport_event`               | Includes the transport event, container, shipment, and location records that are available.                                                                                          |
| `shipment.estimated.arrival`                                                                                  | `estimated_event`               | Includes the estimate event and related shipment records.                                                                                                                            |
| `container.updated`                                                                                           | `container_updated_event`       | Includes a `changeset` describing changed container attributes.                                                                                                                      |
| `container.created`                                                                                           | `container_created_event`       | Includes the new container and related shipment.                                                                                                                                     |
| `container.pickup_lfd.changed` and the `pickup_lfd_line` / `pickup_lfd_terminal` / `pickup_lfd_rail` variants | `transport_event`               | The transport event's `value` attribute carries the new Last Free Day. The container with updated LFD fields may also be included, as in the `container.pickup_lfd.changed` example. |
| `document.*`                                                                                                  | document-related event resource | Available for accounts using document processing. See [Document Processing Workflows](/api-docs/in-depth-guides/document-processing-workflows).                                      |

## Included resources

Webhook payloads may include:

| Resource type             | When included                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| `tracking_request`        | Included for tracking request lifecycle events and related shipment updates.                |
| `shipment`                | Included when the event relates to a shipment or one of its containers.                     |
| `container`               | Included for container lifecycle, status, availability, and milestone events.               |
| `transport_event`         | Included for `container.transport.*` milestone events and LFD or appointment change events. |
| `estimated_event`         | Included for ETA change events.                                                             |
| `container_updated_event` | Included for `container.updated` events.                                                    |
| `port`                    | Included when a payload references a port record.                                           |
| `terminal`                | Included when a payload references a terminal record.                                       |

Other resource types — such as `vessel`, `rail_terminal`, and `metro_area` — can appear for specific events. The webhook endpoint that received the delivery is referenced through the `webhook` relationship on the notification, not serialized in `included`.

Do not require every resource to be present. Carrier, terminal, and event data can arrive at different times.

## Container update changesets

For `container.updated` events, the event resource includes a `changeset` object. Each key is a changed field. The value is a two-item array: `[previous_value, current_value]`.

```json theme={null}
{
  "changeset": {
    "pickup_lfd": [null, "2026-05-14T07:00:00Z"],
    "available_for_pickup": [false, true]
  }
}
```

Common changed fields include:

* `fees_at_pod_terminal`
* `holds_at_pod_terminal`
* `pickup_lfd`
* `pickup_lfd_line`
* `pickup_lfd_rail`
* `pickup_appointment_at`
* `available_for_pickup`
* `pod_terminal`

The event's `timestamp` attribute tells you when Terminal49 picked up the changes from the terminal.

For `pod_terminal`, the changeset values are terminal record IDs, not names:

```json theme={null}
{
  "changeset": {
    "pod_terminal": ["0ef5519f-3bde-4d1f-a327-f4f2d833dc7b", "08831e36-676a-4bd4-9c26-c8ab7dbfe73e"]
  }
}
```

Resolve the IDs through the `terminal` resources serialized in `included`.

<Note>
  The `container_updated_event` also has a `terminal` relationship that indicates where the data came from. Currently this is always the POD terminal; in the future it may be the final destination terminal or an off-dock location.
</Note>

## Related

* [Event Catalog](/api-docs/webhooks/event-catalog) - canonical event names
* [Payload Examples](/api-docs/useful-info/webhook-events-examples) - complete sample JSON
* [Set Up Webhooks](/api-docs/in-depth-guides/webhooks) - create and secure webhook endpoints
* [Webhook Notifications API](/api-docs/api-reference/webhook-notifications/list-webhook-notifications) - inspect notification delivery status