Webhooks
Shipment update (format 5.0)
Sent to your configured endpoint whenever a Shipment has new events.
One webhook per update cycle, even when several triggers fire — the
trigger array lists every trigger the cycle satisfied.
Delivery: HTTPS POST, JSON body. Respond with HTTP 200. Without a 200, Perform.AI retries up to 3 times, 5 minutes apart, then stops.
Authentication: each request carries an HTTP-X-Hmac-SHA256 header
— the HMAC-SHA256 of the raw request body, keyed with the
Authentication Key from Integrations > Webhooks. Recompute and
compare to verify the sender.
Your account is configured for exactly one payload format version — confirm which with your account team.
WEBHOOK
shipment-update-v5-0
{
"data": {
"note": "Webhook capture test shipment - synthetic data",
"tags": [
"doctest",
"webhook-capture",
"priority"
],
"order": {
"order_id": "ORD-DOCTEST-WH50",
"order_uuid": "441f678f-f564-4391-96ae-59fab43a7244",
"source_name": "DocTest Store",
"source_type": "webshop",
"created_date": "2026-09-21T04:33:01+00:00",
"updated_date": "2026-09-21T04:33:01+00:00",
"order_reference": "ORD-WH50-REF"
},
"source": "api",
"status": "active",
"weight": {
"unit": "g",
"amount": 1200
},
"carrier": {
"id": "ppmk07",
"name": "Perform.AI Mock Carrier 07",
"contact": "+ 49 (0) 228 4333112",
"language": null,
"site_link": "www.dhl.de",
"country_iso": [
"DE"
],
"supported_languages": [
"de",
"es",
"nl",
"en",
"fr",
"cs",
"pl"
]
},
"cod_value": {
"amount": 20,
"currency": "EUR"
},
"documents": [],
"all_events": [
{
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
},
{
"time": "2026-09-21T08:00:00+02:00",
"event": "Order packed at warehouse",
"phase": null,
"location": {
"place": "Berlin, Berlin, Germany"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {
"dock": "D4"
}
}
],
"dimensions": {
"unit": "cm",
"width": 20,
"height": 15,
"length": 30
},
"item_count": 2,
"new_events": [
{
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
}
],
"to_address": {
"city": "Singapore",
"full": "Jane Doe, 52 Bread Street, 049145, Singapore, Singapore",
"email": null,
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": null,
"country": "Singapore",
"last_name": "Doe",
"first_name": "Jane",
"postal_code": 49145,
"address_name": null,
"country_code": "SG",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_id": "SHP-DOCTEST-WH50-001",
"created_date": "2026-09-21T04:33:01+00:00",
"from_address": {
"city": "Berlin",
"full": "12 Hafenstrasse, 10115, Berlin, Germany",
"email": null,
"line1": "12 Hafenstrasse",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": null,
"country": "Germany",
"last_name": null,
"first_name": null,
"postal_code": "10115",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"latest_event": {
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
},
"payment_type": "credit card",
"updated_date": "2026-09-21T04:34:05+00:00",
"current_phase": {
"key": null,
"name": null
},
"sales_channel": "ecommerce shop",
"shipment_uuid": "0834801c-9a23-43af-b3e6-eeceaed9fc8c",
"packaging_type": "box",
"return_address": {
"city": "Berlin",
"full": "9 Retour Lane, 10245, Berlin, Germany",
"email": null,
"line1": "9 Retour Lane",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": "DocTest Returns Center",
"country": "Germany",
"last_name": null,
"first_name": null,
"postal_code": "10245",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"sender_address": {
"city": "Berlin",
"full": "Perform Warehouse, 12 Hafenstrasse, 10115, Berlin, Germany",
"email": "warehouse@example.com",
"line1": "12 Hafenstrasse",
"line2": null,
"line3": null,
"phone": "+493012345678",
"region": null,
"tax_id": null,
"company": "DocTest GmbH",
"country": "Germany",
"last_name": "Warehouse",
"first_name": "Perform",
"postal_code": "10115",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_value": {
"amount": 159.8,
"currency": "EUR"
},
"shipping_costs": [
{
"name": "base rate",
"reference": "sc-base",
"unit_cost": {
"amount": null,
"currency": ""
},
"total_cost": {
"amount": 8.9,
"currency": "EUR"
},
"unit_quantity": null
},
{
"name": "fuel surcharge",
"reference": "sc-fuel",
"unit_cost": {
"amount": 1.05,
"currency": "EUR"
},
"total_cost": {
"amount": 2.1,
"currency": "EUR"
},
"unit_quantity": 2
}
],
"additional_info": {
"campaign": "doctest",
"customer_segment": "vip"
},
"tracking_number": "PPDOCTEST10005001",
"linked_shipments": [
{
"carrier": {
"id": "feexgl",
"name": "FedEx",
"contact": "+1 800 247 4747",
"language": [
"en"
],
"site_link": "www.fedex.com",
"country_iso": [
"CA",
"US",
"MX",
"BR",
"CL",
"DM",
"BM",
"AU",
"GU",
"NZ",
"SG",
"LA",
"JP",
"TW",
"KR",
"PH",
"VN"
],
"supported_languages": [
"en",
"es"
]
},
"tracking_number": "PPDOCTESTLINKED01",
"carrier_reference": "fedex"
}
],
"shipping_service": "standard",
"carrier_reference": "dhlm",
"expected_delivery": {
"to": "2026-09-26T10:00:00+00:00",
"from": "2026-09-24T01:00:00+00:00"
},
"recipient_address": {
"city": "Singapore",
"full": "Ms Jane Doe, 52 Bread Street, The Building, #35-55, 049145, Singapore, Singapore, Singapore, Singapore",
"email": "jane.doe@example.com",
"line1": "52 Bread Street",
"line2": "The Building",
"line3": "#35-55",
"phone": "+6598765432",
"region": "Singapore",
"tax_id": "T111555",
"company": "Do or Donuts",
"country": "Singapore",
"last_name": "Doe",
"first_name": "Jane",
"postal_code": 49145,
"address_name": "Jane Home",
"country_code": "SG",
"location_type": "residential",
"entity_reference": "C212",
"state_or_province": "Singapore"
},
"notification_email": [
"jane.doe@example.com",
"ops@example.com"
],
"notification_phone": [
"+6598765432"
],
"shipment_reference": "WH50-REF-A",
"total_shipping_cost": {
"amount": 11,
"currency": "EUR"
},
"additional_reference": "WH50-REF-B",
"description_of_goods": "sports shoes and socks",
"handling_instructions": "keep dry",
"tracking_page_reference": null
},
"trigger": [
"all_events"
],
"version": "5.0.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. Any other status triggers the retry cycle.
⌘I
{
"data": {
"note": "Webhook capture test shipment - synthetic data",
"tags": [
"doctest",
"webhook-capture",
"priority"
],
"order": {
"order_id": "ORD-DOCTEST-WH50",
"order_uuid": "441f678f-f564-4391-96ae-59fab43a7244",
"source_name": "DocTest Store",
"source_type": "webshop",
"created_date": "2026-09-21T04:33:01+00:00",
"updated_date": "2026-09-21T04:33:01+00:00",
"order_reference": "ORD-WH50-REF"
},
"source": "api",
"status": "active",
"weight": {
"unit": "g",
"amount": 1200
},
"carrier": {
"id": "ppmk07",
"name": "Perform.AI Mock Carrier 07",
"contact": "+ 49 (0) 228 4333112",
"language": null,
"site_link": "www.dhl.de",
"country_iso": [
"DE"
],
"supported_languages": [
"de",
"es",
"nl",
"en",
"fr",
"cs",
"pl"
]
},
"cod_value": {
"amount": 20,
"currency": "EUR"
},
"documents": [],
"all_events": [
{
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
},
{
"time": "2026-09-21T08:00:00+02:00",
"event": "Order packed at warehouse",
"phase": null,
"location": {
"place": "Berlin, Berlin, Germany"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {
"dock": "D4"
}
}
],
"dimensions": {
"unit": "cm",
"width": 20,
"height": 15,
"length": 30
},
"item_count": 2,
"new_events": [
{
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
}
],
"to_address": {
"city": "Singapore",
"full": "Jane Doe, 52 Bread Street, 049145, Singapore, Singapore",
"email": null,
"line1": "52 Bread Street",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": null,
"country": "Singapore",
"last_name": "Doe",
"first_name": "Jane",
"postal_code": 49145,
"address_name": null,
"country_code": "SG",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_id": "SHP-DOCTEST-WH50-001",
"created_date": "2026-09-21T04:33:01+00:00",
"from_address": {
"city": "Berlin",
"full": "12 Hafenstrasse, 10115, Berlin, Germany",
"email": null,
"line1": "12 Hafenstrasse",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": null,
"country": "Germany",
"last_name": null,
"first_name": null,
"postal_code": "10115",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"latest_event": {
"time": "2026-09-21T10:30:00+02:00",
"event": "Handed over to carrier",
"phase": null,
"location": {
"place": "Berlin Hub"
},
"timezone": "Etc/GMT-2",
"event_key": null,
"phase_key": null,
"carrier_name": "Perform.AI Mock Carrier 07",
"additional_info": {}
},
"payment_type": "credit card",
"updated_date": "2026-09-21T04:34:05+00:00",
"current_phase": {
"key": null,
"name": null
},
"sales_channel": "ecommerce shop",
"shipment_uuid": "0834801c-9a23-43af-b3e6-eeceaed9fc8c",
"packaging_type": "box",
"return_address": {
"city": "Berlin",
"full": "9 Retour Lane, 10245, Berlin, Germany",
"email": null,
"line1": "9 Retour Lane",
"line2": null,
"line3": null,
"phone": null,
"region": null,
"tax_id": null,
"company": "DocTest Returns Center",
"country": "Germany",
"last_name": null,
"first_name": null,
"postal_code": "10245",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"sender_address": {
"city": "Berlin",
"full": "Perform Warehouse, 12 Hafenstrasse, 10115, Berlin, Germany",
"email": "warehouse@example.com",
"line1": "12 Hafenstrasse",
"line2": null,
"line3": null,
"phone": "+493012345678",
"region": null,
"tax_id": null,
"company": "DocTest GmbH",
"country": "Germany",
"last_name": "Warehouse",
"first_name": "Perform",
"postal_code": "10115",
"address_name": null,
"country_code": "DE",
"location_type": null,
"entity_reference": null,
"state_or_province": null
},
"shipment_value": {
"amount": 159.8,
"currency": "EUR"
},
"shipping_costs": [
{
"name": "base rate",
"reference": "sc-base",
"unit_cost": {
"amount": null,
"currency": ""
},
"total_cost": {
"amount": 8.9,
"currency": "EUR"
},
"unit_quantity": null
},
{
"name": "fuel surcharge",
"reference": "sc-fuel",
"unit_cost": {
"amount": 1.05,
"currency": "EUR"
},
"total_cost": {
"amount": 2.1,
"currency": "EUR"
},
"unit_quantity": 2
}
],
"additional_info": {
"campaign": "doctest",
"customer_segment": "vip"
},
"tracking_number": "PPDOCTEST10005001",
"linked_shipments": [
{
"carrier": {
"id": "feexgl",
"name": "FedEx",
"contact": "+1 800 247 4747",
"language": [
"en"
],
"site_link": "www.fedex.com",
"country_iso": [
"CA",
"US",
"MX",
"BR",
"CL",
"DM",
"BM",
"AU",
"GU",
"NZ",
"SG",
"LA",
"JP",
"TW",
"KR",
"PH",
"VN"
],
"supported_languages": [
"en",
"es"
]
},
"tracking_number": "PPDOCTESTLINKED01",
"carrier_reference": "fedex"
}
],
"shipping_service": "standard",
"carrier_reference": "dhlm",
"expected_delivery": {
"to": "2026-09-26T10:00:00+00:00",
"from": "2026-09-24T01:00:00+00:00"
},
"recipient_address": {
"city": "Singapore",
"full": "Ms Jane Doe, 52 Bread Street, The Building, #35-55, 049145, Singapore, Singapore, Singapore, Singapore",
"email": "jane.doe@example.com",
"line1": "52 Bread Street",
"line2": "The Building",
"line3": "#35-55",
"phone": "+6598765432",
"region": "Singapore",
"tax_id": "T111555",
"company": "Do or Donuts",
"country": "Singapore",
"last_name": "Doe",
"first_name": "Jane",
"postal_code": 49145,
"address_name": "Jane Home",
"country_code": "SG",
"location_type": "residential",
"entity_reference": "C212",
"state_or_province": "Singapore"
},
"notification_email": [
"jane.doe@example.com",
"ops@example.com"
],
"notification_phone": [
"+6598765432"
],
"shipment_reference": "WH50-REF-A",
"total_shipping_cost": {
"amount": 11,
"currency": "EUR"
},
"additional_reference": "WH50-REF-B",
"description_of_goods": "sports shoes and socks",
"handling_instructions": "keep dry",
"tracking_page_reference": null
},
"trigger": [
"all_events"
],
"version": "5.0.0",
"notification_type": "shipment_notification"
}