Event Payloads And Tracking Statuses

This reference shows example payloads for every outgoing webhook event Shipit currently supports.

Notes about the examples

The payloads below reflect the current emitted payload structure.
Some values can be null depending on the shipment or transaction.
Wallet credit and debit events currently do not include a top-level event field.

`shipment.booked`

{
  "event": "shipment.booked",
  "shipment": {
    "id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
    "shipit_number": "SHP-2024-001234",
    "tracking_number": "1Z999AA10123456784",
    "tracking_number_2": null,
    "service_id": "ups_express",
    "carrier_code": "ups",
    "reference": "ORDER-12345",
    "external_id": "ext-abc-123",
    "price": "15.99",
    "currency": "EUR",
    "created_at": "2024-01-15T10:30:00+00:00"
  },
  "sender": {
    "name": "Acme Corp",
    "email": "[email protected]",
    "phone": "+358401234567",
    "street": "Warehouse Street 10",
    "postcode": "00100",
    "city": "Helsinki",
    "country": "FI"
  },
  "receiver": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+358409876543",
    "street": "Customer Road 5",
    "postcode": "00200",
    "city": "Espoo",
    "country": "FI"
  }
}

`shipment.failed`

{
  "event": "shipment.failed",
  "error_message": "Recipient address could not be validated",
  "shipment_data": {
    "serviceId": "dhl_express",
    "reference": "ORDER-12346",
    "externalId": "ext-abc-124",
    "sender": {
      "name": "Acme Corp"
    },
    "receiver": {
      "name": "John Doe"
    }
  }
}

`shipment.tracking_event_updated`

{
  "event": "shipment.tracking_event_updated",
  "shipment": {
    "id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
    "shipit_number": "SHP-2024-001234",
    "tracking_number": "1Z999AA10123456784",
    "tracking_number_2": null,
    "service_id": "ups_express",
    "carrier_code": "ups",
    "reference": "ORDER-12345",
    "external_id": "ext-abc-123"
  },
  "tracking_event": {
    "id": "01hxtrackingevent1234567890",
    "status": "DELIVERED",
    "shipment_tracking_number": "1Z999AA10123456784",
    "parcel_tracking_number": "1Z999AA10123456784",
    "return_tracking_number": null,
    "description": {
      "en": "Shipment delivered"
    },
    "information": null,
    "instruction": null,
    "location": {
      "city": "Helsinki",
      "country": "FI"
    },
    "metadata": {
      "carrier_event_code": "DELIVERED"
    },
    "happened_at": "2024-01-15T10:30:00+00:00",
    "created_at": "2024-01-15T10:30:00+00:00",
    "updated_at": "2024-01-15T10:35:00+00:00"
  }
}

`pending_shipment.created`

{
  "event": "pending_shipment.created",
  "pending_shipment": {
    "id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
    "external_id": "pending-ext-123",
    "status": "pending",
    "source": "api",
    "request": {
      "receiver": {
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "parcels": [
        {
          "weight": 2.5,
          "length": 30,
          "width": 20,
          "height": 10
        }
      ]
    },
    "created_at": "2024-01-15T10:00:00+00:00"
  }
}

`pending_shipment.completed`

{
  "event": "pending_shipment.completed",
  "pending_shipment": {
    "id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
    "external_id": "pending-ext-123",
    "status": "completed",
    "source": "api",
    "request": {
      "receiver": {
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "parcels": [
        {
          "weight": 2.5,
          "length": 30,
          "width": 20,
          "height": 10
        }
      ]
    },
    "created_at": "2024-01-15T10:00:00+00:00",
    "updated_at": "2024-01-15T10:30:00+00:00"
  }
}

`wallet.credited`

{
  "transaction_id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
  "amount": "100.00",
  "vat": "24.00",
  "vat_percent": "24",
  "comment": "Account top-up",
  "created_at": "2024-01-15T10:00:00+00:00",
  "user_id": "12345"
}

`wallet.debited`

{
  "transaction_id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
  "amount": "-15.99",
  "vat": "-3.84",
  "vat_percent": "24",
  "comment": "Payment for shipment SHP-2024-001234",
  "shipment_id": "01h2x4y6z8a9b0c1d2e3f4g5h7",
  "created_at": "2024-01-15T10:30:00+00:00",
  "user_id": "12345"
}

`wallet.low_balance`

{
  "event": "wallet.low_balance",
  "wallet": {
    "user_id": "01h2x4y6z8a9b0c1d2e3f4g5h6",
    "current_balance": 500,
    "threshold": 1000,
    "balance_below_threshold": true,
    "difference": 500
  },
  "timestamp": "2024-01-15T11:00:00+00:00"
}

Tracking event status values

The tracking_event.status value in shipment.tracking_event_updated can be any of the following enum values:

Status	Meaning
`ADVANCED_SHIPPING_NOTICE`	Carrier has received advance notice before physical handoff.
`AT_OFFICE_OF_EXCHANGE`	Shipment reached an exchange or transfer office.
`ATTEMPTED_DELIVERY`	Carrier attempted delivery.
`AWAITING_DELIVERY`	Shipment is waiting for final delivery.
`AWAITING_DELIVERY_TIME_SELECTION`	Recipient must choose a delivery time.
`AWAITING_DISPATCH`	Shipment is waiting to be dispatched.
`CANCELLED`	Shipment or transport leg was cancelled.
`CASH_ON_DELIVERY`	Cash on delivery step is involved in the shipment flow.
`COLLECTED`	Shipment has been collected.
`CONFIRMED`	Carrier confirmed the shipment or event.
`CONSOLIDATED`	Shipment was consolidated with other freight.
`DAMAGED`	Carrier reported damage.
`DECONSOLIDATED`	Shipment was separated from a consolidated flow.
`DELAYED`	Shipment is delayed.
`DELETED`	Shipment or event was deleted by the upstream source.
`DELIVERED`	Shipment was delivered.
`DELIVERY_CANCELLED`	Planned delivery was cancelled.
`DELIVERY_IMPOSSIBLE`	Carrier could not complete delivery.
`DELIVERY_REFUSED`	Recipient refused the delivery.
`DELIVERY_TIME_SELECTED`	Recipient selected a delivery time.
`DISPATCHED`	Shipment was dispatched.
`EN_ROUTE`	Shipment is moving through the network.
`EXCEPTION`	Carrier reported an exception or irregularity.
`EXTRA_SERVICE`	Extra service information was attached to the event.
`IN_CUSTOMS`	Shipment is in customs handling.
`LOST`	Carrier reported the shipment as lost.
`NOTICE_OF_ARRIVAL`	Arrival notice was sent or generated.
`OTHER`	Carrier event did not map to a more specific status.
`OUT_FOR_DELIVERY`	Shipment is out for delivery.
`PARTIALLY_DELIVERED`	Only part of the shipment was delivered.
`PICK_UP_CANCELLED`	A pickup was cancelled.
`RECIPIENT_CONTACTED`	Carrier contacted the recipient.
`REGISTERED`	Shipment was registered in the carrier system.
`REROUTING`	Shipment is being rerouted.
`RETURNED`	Shipment was returned.
`RETURNING`	Shipment is on its way back to the sender.
`SORTING`	Shipment is being sorted.
`TEST`	Test status used by an upstream source.
`UNCONFIRMED`	Event exists but is not yet confirmed.
`UNKNOWN`	Status is unknown.
`UNSUCCESSFUL_DELIVERY`	Delivery failed.
`UNSUCCESSFUL_DELIVERY_ATTEMPT`	Delivery attempt failed.
`UNSUCCESSFUL_DISPATCH`	Dispatch failed.
`UNSUCCESSFUL_DISPATCH_ATTEMPT`	Dispatch attempt failed.