Skip to main content

​
Webhooks

Webhooks allow you to receive real-time notifications when events occur in your PrimeFreight account. Instead of polling the API for updates, webhooks will send HTTP POST requests to your specified URL when events happen.

​
Webhook Events

PrimeFreight sends webhook notifications for a comprehensive range of events including:

​
Container Transport Events

  • container.transport.vessel_arrived - Vessel arrives at port
  • container.transport.vessel_discharged - Container discharged from vessel
  • container.transport.vessel_loaded - Container loaded onto vessel
  • container.transport.vessel_departed - Vessel departs from port
  • container.transport.vessel_berthed - Vessel berthed at terminal
  • container.transport.rail_departed - Container departs by rail
  • container.transport.rail_arrived - Container arrives by rail
  • container.transport.rail_loaded - Container loaded onto rail
  • container.transport.rail_unloaded - Container unloaded from rail
  • container.transport.transshipment_arrived - Container arrives at transshipment port
  • container.transport.transshipment_discharged - Container discharged at transshipment
  • container.transport.transshipment_loaded - Container loaded at transshipment
  • container.transport.transshipment_departed - Container departs transshipment
  • container.transport.feeder_arrived - Feeder vessel arrives
  • container.transport.feeder_discharged - Container discharged from feeder
  • container.transport.feeder_loaded - Container loaded onto feeder
  • container.transport.feeder_departed - Feeder vessel departs
  • container.transport.empty_out - Container emptied out
  • container.transport.full_in - Container filled in
  • container.transport.full_out - Container filled out
  • container.transport.empty_in - Container emptied in
  • container.transport.arrived_at_inland_destination - Container arrived at inland destination
  • container.transport.estimated.arrived_at_inland_destination - Estimated arrival at inland destination
  • container.transport.available - Container available for pickup

​
Container Events

  • container.created - New container created
  • container.updated - Container information updated
  • container.pod_terminal_changed - Port of discharge terminal changed
  • container.pickup_lfd.changed - Pickup last free day changed

​
Shipment Events

  • shipment.estimated.arrival - Shipment arrival time updated

​
Tracking Request Events

  • tracking_request.succeeded - Tracking request successfully created
  • tracking_request.failed - Tracking request failed
  • tracking_request.awaiting_manifest - Tracking request waiting for manifest
  • tracking_request.tracking_stopped - Tracking request stopped

​
Webhook Payload Structure

All webhook payloads follow a consistent JSON:API structure with included related resources. Here’s an example of the type of notification you would receive: 
[
  {
    "data": {
      "id": "17d8ef84-eef3-4780-8c6f-ad47b7c940e2",
      "type": "webhook_notification",
      "attributes": {
        "id": "17d8ef84-eef3-4780-8c6f-ad47b7c940e2",
        "event": "container.updated",
        "delivery_status": "pending",
        "created_at": "2025-08-28T19:26:48Z"
      },
      "relationships": {
        "reference_object": {
          "data": {
            "id": "892bfc0c-0f11-4e0a-9938-fe6f932c4d04",
            "type": "container_updated_event"
          }
        },
        "webhook": {
          "data": {
            "id": "c4b6ee2c-b3a9-48b2-882f-89e3c21f998b",
            "type": "webhook"
          }
        },
        "webhook_notification_logs": {
          "data": []
        }
      }
    },
    "included": [
      {
        "id": "bd02b718-3ab3-4277-af0a-598572eeea54",
        "type": "shipment",
        "attributes": {
          "created_at": "2025-07-20T09:24:20Z",
          "ref_numbers": [],
          "tags": [],
          "bill_of_lading_number": "SEKU5970536",
          "normalized_number": "SEKU5970536",
          "shipping_line_scac": "CMDU",
          "shipping_line_name": "CMA CGM",
          "shipping_line_short_name": "CMA CGM",
          "customer_name": "Prime Freight",
          "port_of_lading_locode": "BDCGP",
          "port_of_lading_name": "Chittagong",
          "port_of_discharge_locode": "CAHAL",
          "port_of_discharge_name": "Halifax",
          "pod_vessel_name": "CMA CGM NORMA",
          "pod_vessel_imo": "9299812",
          "pod_voyage_number": "1TUERN1MA",
          "pol_etd_at": "2025-07-20T04:37:00Z",
          "pol_atd_at": "2025-07-20T01:16:28Z",
          "pol_timezone": "Asia/Dhaka",
          "pod_eta_at": "2025-08-29T15:00:00Z",
          "pod_timezone": "America/New_York"
        }
      },
      {
        "id": "12b8f16e-f74c-457f-aa28-9262336e10d1",
        "type": "container",
        "attributes": {
          "number": "SEKU5970536",
          "created_at": "2025-07-20T09:24:21Z",
          "ref_numbers": [],
          "current_status": "on_ship",
          "equipment_type": "dry",
          "equipment_length": 40,
          "equipment_height": "high_cube",
          "holds_at_pod_terminal": [
            {
              "status": "pending",
              "name": "customs",
              "description": "NONE"
            }
          ],
          "available_for_pickup": false,
          "location_at_pod_terminal": "VESSEL 01404086",
          "terminal_checked_at": "2025-08-28T19:26:48Z"
        }
      },
      {
        "id": "892bfc0c-0f11-4e0a-9938-fe6f932c4d04",
        "type": "container_updated_event",
        "attributes": {
          "changeset": {
            "holds_at_pod_terminal": [
              [
                {
                  "name": "freight",
                  "status": "pending",
                  "description": "NONE"
                },
                {
                  "name": "customs",
                  "status": "pending",
                  "description": "NONE"
                }
              ],
              [
                {
                  "name": "customs",
                  "status": "pending",
                  "description": "NONE"
                }
              ]
            ]
          },
          "timestamp": "2025-08-28T19:26:48Z",
          "data_source": "terminal",
          "timezone": "America/New_York"
        }
      }
    ]
  }
]
Webhook notifications are only sent if you have at least one active webhook configured in your account.