shipment/shipping_event

Overview

Property	Value
Webhook type	shipment/shipping_event
Kafka topic	shipment.shipping_event
Direction	Platform → Your endpoint

Description

Fired every time a new tracking event is recorded on a shipment. This provides real-time tracking updates as the parcel moves through the carrier network. Each carrier scan or status change generates one shipment/shipping_event.

Trigger Conditions

• A carrier integration pushes a new tracking event
• An operator manually adds a tracking event
• The fulfillment service pushes a status update (packed, handed over to carrier, etc.)
• Any call to the internal shipment.setEvent() method

Message Envelope

{
  "header": {
    "organizationId": "org_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "messageId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "webhookId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "type": "shipment/shipping_event",
    "date": "2024-03-16T06:05:00.000Z"
  },
  "body": { ... }
}

Body — Property Table

The body has the same shape as shipment/created — the full shipment object is sent, including the growing events array. See shipment-created.md for the complete property table.

The newly added event is always the last entry in the events array, but all previous events are included for context.

Key fields to observe:

Field	Description
lastEvent	Updated to the new event code
events	Full history — the triggering event is the most recently dated entry

ShippingEventEnum values (see shipment-created.md for full description):

Code	Typical meaning
NEW	Shipment registered
INFO_RECEIVED	Label created, not yet picked up
PENDING	Awaiting pickup
IN_TRANSIT	Moving through carrier network
OUT_FOR_DELIVERY	On delivery vehicle
ATTEMPT_FAIL	Delivery attempt failed
AVAILABLE_FOR_PICKUP	At pickup point
DELIVERED	Delivered successfully
DELIVERED_TO_SENDER	Back to sender
EXCEPTION	Exception (damage, loss, etc.)
RETURNED_TO_SENDER	In transit back to sender
EXPIRED	Label expired

Full JSON Payload Sample

Example: IN_TRANSIT event

{
  "header": {
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "messageId": "b0c1d2e3-f4a5-6789-bcde-456789012345",
    "webhookId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "shipment/shipping_event",
    "date": "2024-03-16T06:05:00.000Z"
  },
  "body": {
    "id": "f2a3b4c5-d6e7-8901-fabc-678901234567",
    "externalId": "CLS-9387263847",
    "locationId": "f0a1b2c3-d4e5-6789-f0ab-123456789012",
    "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "shippingMethodId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "shippingMethodName": "Colissimo Domicile",
    "lastEvent": "IN_TRANSIT",
    "state": "OPENED",
    "label": "1Z999AA10123456784",
    "reference": "SHP-2024-001234",
    "trackingUrl": "https://www.laposte.fr/outils/track-a-parcel?code=1Z999AA10123456784",
    "tracking": "1Z999AA10123456784",
    "meta": null,
    "issuedAt": "2024-03-15T16:00:00.000Z",
    "createdAt": "2024-03-15T16:00:00.000Z",
    "deliveredAt": null,
    "firstAttemptedAt": null,
    "estimatedAt": "2024-03-17T18:00:00.000Z",
    "weight": 1.5,
    "weightSellingUnit": "kg",
    "volume": null,
    "volumeSellingUnit": "l",
    "format": "S",
    "addresses": [
      {
        "id": "a3b4c5d6-e7f8-9012-abcd-789012345678",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "type": "DELIVERY",
        "fullname": "Alice Dupont",
        "email": "alice.dupont@example.com",
        "address": "12 Rue de la Paix",
        "addressComplement": "Apt 4B",
        "zipcode": "75001",
        "city": "Paris",
        "country": "FR",
        "state": null,
        "phone": "+33612345678",
        "mobile": null,
        "comments": null
      }
    ],
    "details": [
      {
        "id": "c5d6e7f8-a9b0-1234-cdef-901234567890",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "orderLineId": "c9d0e1f2-a3b4-5678-cdef-789012345678",
        "deliveryOrderLineId": "b2c3d4e5-f6a7-8901-bcde-012345678901",
        "label": "T-Shirt Blanc Taille M",
        "quantity": 2,
        "batchNumber": null,
        "limitUsageDate": null
      }
    ],
    "events": [
      {
        "id": "d6e7f8a9-b0c1-2345-defa-012345678901",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "event": "INFO_RECEIVED",
        "eventCode": null,
        "eventMessage": null,
        "eventDescription": null,
        "eventCountry": null,
        "eventDate": null,
        "date": "2024-03-15T16:00:00.000Z",
        "comment": null,
        "meta": null
      },
      {
        "id": "e7f8a9b0-c1d2-3456-efab-123456789012",
        "shipmentId": "f2a3b4c5-d6e7-8901-fabc-678901234567",
        "event": "IN_TRANSIT",
        "eventCode": "D101",
        "eventMessage": "Parcel in transit at sorting center",
        "eventDescription": "Parcel scanned at Rungis sorting center",
        "eventCountry": "FR",
        "eventDate": "2024-03-16T06:00:00.000Z",
        "date": "2024-03-16T06:05:00.000Z",
        "comment": null,
        "meta": null
      }
    ]
  }
}

Related Events

• shipment/created — initial shipment creation
• shipment/completed — fired when delivery is confirmed (DELIVERED event)

Notes

• shipment/shipping_event fires for every new tracking event. If a shipment goes through 10 carrier scans, you receive 10 events.
• The full events array is always included. Use the date field on each ShippingEvent for ordering.
• eventDate is the carrier-reported timestamp (may differ from date which is the HappyColis recording time).
• When lastEvent becomes DELIVERED, a shipment/completed event will also be emitted immediately after.
• The EXCEPTION event does NOT automatically trigger shipment/completed — monitor for it to implement custom exception handling.
• eventCode and eventMessage are carrier-specific and vary by shipping method.
• There is no delta — every event includes the full shipment state with all previous events.