Webhooks
Shipment update (format 5.2)
Everything in format 5.0, plus: shipment_type, a returns object for
Return Shipments, line_items, collection_point, rating,
tracking_page_url, pod_url, parcel_recipient_information, and the
enriched event.location (full address, coordinates, timezone) on
every event object. The emitted version value for this format is
5.2.0.
Format 5.2 is enabled automatically when your account opts into the Returns module; to use its other additions without Returns, ask your account team to enable it. Delivery and authentication are identical to format 5.0.
WEBHOOK
shipment-update-v5-2
{
"data": {
"note": null,
"tags": [
"dl",
"dl_es",
"sla_warehouse_pending",
"sla_standard_compliant"
],
"order": {
"order_id": "ORD-EXAMPLE-001",
"order_uuid": "00000000-0000-4000-8000-000000000001",
"source_name": null,
"source_type": null,
"created_date": "2026-09-15T15:57:55+00:00",
"updated_date": "2026-09-15T15:57:55+00:00",
"order_reference": null
},
"rating": null,
"source": "api",
"status": "delivered",
"weight": {
"unit": "g",
"amount": 3020
},
"carrier": {
"id": "upsglo",
"name": "UPS",
"contact": "1 866 782 7892",
"language": [
"en"
],
"site_link": "www.ups.com",
"country_iso": [
"US"
],
"supported_languages": [
"en"
]
},
"pod_url": "https://documents.perform.ai/pod/example.pdf",
"returns": null,
"cod_value": null,
"documents": [
{
"name": "Shipping Label",
"type": "shipping_label",
"document_id": "00000000-0000-4000-8000-000000000002",
"file_format": "zpl",
"created_date": "2026-09-15T15:57:57+00:00",
"document_uuid": "00000000-0000-4000-8000-000000000003",
"download_link": "https://documents.perform.ai/labels/example.pdf",
"additional_info": {}
}
],
"all_events": [
{
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
},
{
"time": "2026-09-18T17:12:00+02:00",
"event": "Arrived at Pick-up Point",
"phase": "Out for delivery",
"location": {
"city": "",
"full": "52 Bread Street, 28001",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "",
"region": "",
"country": "",
"latitude": null,
"timezone": null,
"longitude": null,
"postal_code": "28001",
"country_code": "",
"location_type": "",
"formatted_address": "",
"state_or_province": ""
},
"timezone": "Europe/Madrid",
"event_key": "G30",
"phase_key": "G",
"carrier_name": "UPS",
"additional_info": {
"additional_info": "PAPELERIA IGNACIO, 39 CALANDA PASEO , ZARAGOZA, 50010, ES"
}
},
{
"time": "2026-09-18T13:58:00+02:00",
"event": "Arrived at Pick-up Point",
"phase": "Out for delivery",
"location": {
"city": "",
"full": "52 Bread Street, 28001",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "",
"region": "",
"country": "",
"latitude": null,
"timezone": null,
"longitude": null,
"postal_code": "28001",
"country_code": "",
"location_type": "",
"formatted_address": "",
"state_or_province": ""
},
"timezone": "Europe/Madrid",
"event_key": "G30",
"phase_key": "G",
"carrier_name": "UPS",
"additional_info": {
"additional_info": "PAPELERIA IGNACIO, 39 CALANDA PASEO , ZARAGOZA, 50010, ES"
}
}
],
"dimensions": {
"unit": "cm",
"width": null,
"height": null,
"length": null
},
"item_count": 1,
"line_items": [
{
"hs_code": null,
"quantity": "1",
"misc_cost": null,
"product_id": 132193903,
"tax_amount": null,
"product_url": null,
"total_price": "65.29",
"product_cost": null,
"product_name": "MC INT ECO DLN EN80.CW ECOM AMZ JBUA",
"currency_code": "EUR",
"return_reason": null,
"subtotal_cost": null,
"product_weight": "3.02",
"additional_info": null,
"discount_amount": null,
"line_item_weight": "3.02",
"product_category": "HHCMNO",
"product_image_url": null,
"product_reference": "EN80.CW",
"customs_description": null,
"product_description": "MC INT ECO DLN EN80.CW ECOM AMZ JBUA",
"product_weight_unit": "kg",
"line_item_weight_unit": "kg",
"product_origin_country_code": null
}
],
"new_events": [
{
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
}
],
"to_address": {
"city": "Zaragoza",
"full": "Jane, 52 Bread Street, 28001, Zaragoza, Spain",
"email": "jane.doe@example.com",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": null,
"country": "Spain",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "ES",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_id": "SHP-EXAMPLE-OUTBOUND-001",
"created_date": "2026-09-15T15:57:55+00:00",
"from_address": {
"city": "MIGNAGOLA DI CARBONERA",
"full": "Jane, 52 Bread Street, 28001, MIGNAGOLA DI CARBONERA, Italy",
"email": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": "Example Store S.L.",
"country": "Italy",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "IT",
"location_type": null,
"entity_reference": null,
"state_or_province": "IT"
},
"latest_event": {
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
},
"payment_type": "01",
"updated_date": "2026-09-20T08:06:42+00:00",
"current_phase": {
"key": "H",
"name": "Delivery"
},
"sales_channel": "online store",
"shipment_type": "outbound",
"shipment_uuid": "00000000-0000-4000-8000-000000000004",
"packaging_type": "02",
"return_address": null,
"sender_address": {
"city": "MIGNAGOLA DI CARBONERA",
"full": "Jane, 52 Bread Street, 28001, MIGNAGOLA DI CARBONERA, Italy",
"email": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": "Example Store S.L.",
"country": "Italy",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "IT",
"location_type": null,
"entity_reference": null,
"state_or_province": "IT"
},
"shipment_value": null,
"shipping_costs": [],
"additional_info": {
"pickup_point": "example",
"total_charge_value": "example"
},
"tracking_number": "1Z999AA10123456781",
"collection_point": null,
"linked_shipments": [],
"shipping_service": "U3",
"carrier_reference": "ups-standard",
"expected_delivery": {
"to": "2026-09-18T23:59:59+00:00",
"from": "2026-09-18T23:59:59+00:00"
},
"recipient_address": null,
"tracking_page_url": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"notification_email": [
"jane.doe@example.com"
],
"notification_phone": [
"+34612345678"
],
"shipment_reference": null,
"total_shipping_cost": null,
"additional_reference": null,
"description_of_goods": "GOODS",
"handling_instructions": null,
"tracking_page_reference": "dl_es",
"parcel_recipient_information": "Jane Doe"
},
"trigger": [
"successfully_delivered_all_events"
],
"version": "5.2.0",
"notification_type": "shipment_notification"
}Authorizations
Used by every functional endpoint. Generate the token with POST /auth/oauth/token/ and send it as Authorization: Bearer {token}.
Body
application/json
Response
200
Return HTTP 200 to acknowledge receipt.
⌘I
{
"data": {
"note": null,
"tags": [
"dl",
"dl_es",
"sla_warehouse_pending",
"sla_standard_compliant"
],
"order": {
"order_id": "ORD-EXAMPLE-001",
"order_uuid": "00000000-0000-4000-8000-000000000001",
"source_name": null,
"source_type": null,
"created_date": "2026-09-15T15:57:55+00:00",
"updated_date": "2026-09-15T15:57:55+00:00",
"order_reference": null
},
"rating": null,
"source": "api",
"status": "delivered",
"weight": {
"unit": "g",
"amount": 3020
},
"carrier": {
"id": "upsglo",
"name": "UPS",
"contact": "1 866 782 7892",
"language": [
"en"
],
"site_link": "www.ups.com",
"country_iso": [
"US"
],
"supported_languages": [
"en"
]
},
"pod_url": "https://documents.perform.ai/pod/example.pdf",
"returns": null,
"cod_value": null,
"documents": [
{
"name": "Shipping Label",
"type": "shipping_label",
"document_id": "00000000-0000-4000-8000-000000000002",
"file_format": "zpl",
"created_date": "2026-09-15T15:57:57+00:00",
"document_uuid": "00000000-0000-4000-8000-000000000003",
"download_link": "https://documents.perform.ai/labels/example.pdf",
"additional_info": {}
}
],
"all_events": [
{
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
},
{
"time": "2026-09-18T17:12:00+02:00",
"event": "Arrived at Pick-up Point",
"phase": "Out for delivery",
"location": {
"city": "",
"full": "52 Bread Street, 28001",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "",
"region": "",
"country": "",
"latitude": null,
"timezone": null,
"longitude": null,
"postal_code": "28001",
"country_code": "",
"location_type": "",
"formatted_address": "",
"state_or_province": ""
},
"timezone": "Europe/Madrid",
"event_key": "G30",
"phase_key": "G",
"carrier_name": "UPS",
"additional_info": {
"additional_info": "PAPELERIA IGNACIO, 39 CALANDA PASEO , ZARAGOZA, 50010, ES"
}
},
{
"time": "2026-09-18T13:58:00+02:00",
"event": "Arrived at Pick-up Point",
"phase": "Out for delivery",
"location": {
"city": "",
"full": "52 Bread Street, 28001",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "",
"region": "",
"country": "",
"latitude": null,
"timezone": null,
"longitude": null,
"postal_code": "28001",
"country_code": "",
"location_type": "",
"formatted_address": "",
"state_or_province": ""
},
"timezone": "Europe/Madrid",
"event_key": "G30",
"phase_key": "G",
"carrier_name": "UPS",
"additional_info": {
"additional_info": "PAPELERIA IGNACIO, 39 CALANDA PASEO , ZARAGOZA, 50010, ES"
}
}
],
"dimensions": {
"unit": "cm",
"width": null,
"height": null,
"length": null
},
"item_count": 1,
"line_items": [
{
"hs_code": null,
"quantity": "1",
"misc_cost": null,
"product_id": 132193903,
"tax_amount": null,
"product_url": null,
"total_price": "65.29",
"product_cost": null,
"product_name": "MC INT ECO DLN EN80.CW ECOM AMZ JBUA",
"currency_code": "EUR",
"return_reason": null,
"subtotal_cost": null,
"product_weight": "3.02",
"additional_info": null,
"discount_amount": null,
"line_item_weight": "3.02",
"product_category": "HHCMNO",
"product_image_url": null,
"product_reference": "EN80.CW",
"customs_description": null,
"product_description": "MC INT ECO DLN EN80.CW ECOM AMZ JBUA",
"product_weight_unit": "kg",
"line_item_weight_unit": "kg",
"product_origin_country_code": null
}
],
"new_events": [
{
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
}
],
"to_address": {
"city": "Zaragoza",
"full": "Jane, 52 Bread Street, 28001, Zaragoza, Spain",
"email": "jane.doe@example.com",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": null,
"country": "Spain",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "ES",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_id": "SHP-EXAMPLE-OUTBOUND-001",
"created_date": "2026-09-15T15:57:55+00:00",
"from_address": {
"city": "MIGNAGOLA DI CARBONERA",
"full": "Jane, 52 Bread Street, 28001, MIGNAGOLA DI CARBONERA, Italy",
"email": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": "Example Store S.L.",
"country": "Italy",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "IT",
"location_type": null,
"entity_reference": null,
"state_or_province": "IT"
},
"latest_event": {
"time": "2026-09-20T09:01:00+02:00",
"event": "Successfully delivered",
"phase": "Delivery",
"location": {
"city": "Zaragoza",
"full": "52 Bread Street, 28001, Zaragoza, Spain",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"place": "Zaragoza, Saragossa, Aragon, Spain",
"region": "Aragon",
"country": "Spain",
"latitude": 41.65684,
"timezone": null,
"longitude": -0.87943,
"postal_code": "28001",
"country_code": "ES",
"location_type": "",
"formatted_address": "Zaragoza",
"state_or_province": "Saragossa"
},
"timezone": "Europe/Madrid",
"event_key": "H10",
"phase_key": "H",
"carrier_name": "UPS",
"additional_info": {}
},
"payment_type": "01",
"updated_date": "2026-09-20T08:06:42+00:00",
"current_phase": {
"key": "H",
"name": "Delivery"
},
"sales_channel": "online store",
"shipment_type": "outbound",
"shipment_uuid": "00000000-0000-4000-8000-000000000004",
"packaging_type": "02",
"return_address": null,
"sender_address": {
"city": "MIGNAGOLA DI CARBONERA",
"full": "Jane, 52 Bread Street, 28001, MIGNAGOLA DI CARBONERA, Italy",
"email": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": "+34612345678",
"region": null,
"tax_id": null,
"company": "Example Store S.L.",
"country": "Italy",
"last_name": null,
"first_name": "Jane",
"postal_code": "28001",
"address_name": null,
"country_code": "IT",
"location_type": null,
"entity_reference": null,
"state_or_province": "IT"
},
"shipment_value": null,
"shipping_costs": [],
"additional_info": {
"pickup_point": "example",
"total_charge_value": "example"
},
"tracking_number": "1Z999AA10123456781",
"collection_point": null,
"linked_shipments": [],
"shipping_service": "U3",
"carrier_reference": "ups-standard",
"expected_delivery": {
"to": "2026-09-18T23:59:59+00:00",
"from": "2026-09-18T23:59:59+00:00"
},
"recipient_address": null,
"tracking_page_url": "https://tracking.example-store.com/?pp_tracking_id=EXAMPLE",
"notification_email": [
"jane.doe@example.com"
],
"notification_phone": [
"+34612345678"
],
"shipment_reference": null,
"total_shipping_cost": null,
"additional_reference": null,
"description_of_goods": "GOODS",
"handling_instructions": null,
"tracking_page_reference": "dl_es",
"parcel_recipient_information": "Jane Doe"
},
"trigger": [
"successfully_delivered_all_events"
],
"version": "5.2.0",
"notification_type": "shipment_notification"
}