Last updated

Configuring a Granular Webhook (formerly, Unified Webhook)

Granular webhook configuration is not supported for webhooks on Orders and Loads. There is a separate guide for webhook setup for Orders/Loads.

What is Granular Webhook

Granular Webhook is a set of new webhook APIs that improve upon an existing implementation:

  • Delta. The new webhook indicates what exactly has changed in the shipment.

  • Payload size. Instead of sending the whole shipment payload each time something changes (i.e. ETA), Granular Webhook allows you to configure what kind of information you would like to receive (i.e. such as "event being added") without including the full history of events and positions.

  • Update Frequency. Though the new webhook sends more updates, the payloads are much smaller and allow you to quickly discard events that you are not interested in, reducing load on your database.

  • Filtering. You can specify what shipment events you are interested in, which allows to further reduce the volume of inbound requests.

Configuration

To configure a webhook you send a PUT request to project44 API: Create or update a push configuration.

Specify webhookConfiguration.webhookEventType field to use one of the supported Granular Webhook configurations.

Once the webhook is configured you will start receiving the new messages from our system.

Supported Webhook Types

Webhook Event TypeDescriptionDocumentation
shipments.v1.event.addedSent when a new event is added to a shipmentEvent Added
shipments.v1.event.updatedSent when an existing event is updatedEvent Updated
shipments.v1.event.removedSent when an event is removed from a shipmentEvent Removed
shipments.v1.state.addedSent when a new state is added to a shipmentState Added
shipments.v1.state.updatedSent when an existing state is updatedState Updated
shipments.v1.state.removedSent when a state is removed from a shipmentState Removed
shipments.v1.shipment.createdSent once when a new shipment is createdShipment Created
shipments.v1.shipment.deletedSent when a shipment is deletedShipment Deleted
shipments.v1.exception.addedOrUpdatedSent when an exception is added or updatedException Added/Updated

Example Request

PUT /api/v4/webhooks

For complete base URL information for your region (Americas, Europe), see Getting Started. 

{
  "webhookConfiguration": {
    "webhookEventType": "shipments.v1.event.added"
  },
  "authParams": {},
  "authType": "API_KEY",
  "authenticationMethods": [
    {
      "parameters": {},
      "type": "API_KEY"
    }
  ],
  "configName": "my-event-webhook",
  "method": "POST",
  "methodParams": {},
  "payloadFormat": "JSON",
  "url": "https://example.com",
  "version": 0
}

Filtering Options

Granular Webhooks support filtering by event types and transportation modes. Different filters are available depending on the webhook type.

For detailed filtering configuration, see Webhook Filters.

Including More Information On Webhook Message

By default, each webhook message comes with a minimal context field that is relevant to that message. For example, for shipment events it is only provided with shipment context that includes:

  • id
  • identifiers
  • attributes
  • Created and modified timestamp
  • Share link

Example Message

{
  "eventId": "333d2a1b-d332-4775-8f8e-960e5f538431",
  "eventType": "shipments.v1.event.added",
  "createdDateTime": "2025-03-31T17:01:42.92601441Z",
  "dataType": "EventChange",
  "context": {
    "shipment": {
      "shipmentId": "ac694c91-e308-4329-9584-ee10acb937b3",
      "identifiers": [
        {
          "type": "BILL_OF_LADING",
          "value": "BOL123"
        }
      ],
      "attributes": [],
      "createdDateTime": "2025-03-31T17:01:42.92601441Z",
      "lastModifiedDateTime": "2025-03-31T17:01:42.92601441Z",
      "shipmentShareLink": "..."
    }
  },
  "data": {}
}

You can request additional information to be provided on the message by specifying includeContext configuration on the webhook configuration payload.

"webhookConfiguration": {
  "shipmentV1Event": {
    "includeContext": ["SHIPMENT", "ROUTE", "RELATED_SHIPMENTS"]
  }
}

Supported Context Types

Context TypeDescription
SHIPMENT(default) High-level shipment information that includes identifiers, attributes and shipment ID.
ROUTERoute information of the shipment that includes all stops and route segments.
RELATED_SHIPMENTSList of related (parent or child) shipment IDs.

For detailed examples of each context type, see Context Types.

Example Request

PUT /api/v4/webhooks

{
  "authParams": {},
  "authType": "API_KEY",
  "authenticationMethods": [
    {
      "parameters": {},
      "type": "API_KEY"
    }
  ],
  "configName": "my-event-webhook",
  "method": "POST",
  "methodParams": {},
  "payloadFormat": "JSON",
  "url": "https://example.com",
  "version": 0,
  "webhookConfiguration": {
    "webhookEventType": "shipments.v1.event.added",
    "shipmentV1Event": {
      "includeContext": ["SHIPMENT", "ROUTE", "RELATED_SHIPMENTS"]
    }
  }
}
Previous page
Next page