ParcelParcelAPI docs

API docs Integrations

Webhooks

Markdown

Get a message on your own URL as soon as a shipment is booked.

POSThttps://services.parcelparcel.com/partners-api/v1/hooks/subscribe

Example request

Subscribe to booked shipments More examples

curl --request POST 'https://services.parcelparcel.com/partners-api/v1/hooks/subscribe' \
  --header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
  --header 'Content-Type: application/json' \
  --data '{
  "hookUrl": "https://example.com/parcelparcel/webhook"
}'

Tip: copy the cURL and paste it in Postman under Import, or straight into the URL bar of a new request. Postman fills in the method, headers and body for you. Replace {YourAPIKey}@{YourAPISecret} with your own API key and secret (use your sandbox key while testing), or import the whole Postman Collection.

With a webhook we send the details of a shipment to your own URL as soon as it is booked at the carrier, with the tracking number. You don't have to keep asking the API whether something changed.

Events

EventWhen
shipment_bookedA shipment on your account is booked at the carrier and has a tracking number. This includes shipments booked in MyParcelParcel, not only the ones you book through the API.

Shipments booked with your sandbox key are never sent to the carrier, so they don't trigger a webhook. Use the example payloads to build and test your receiver.

Subscribe

Send your URL as hookUrl. You get the id of the webhook back; keep it if you want to unsubscribe later.

NameValueRequiredComments
hookUrl(string)requiredThe URL we send the webhook to, for example https://example.com/parcelparcel/webhook.

Response

JSON
{
  "id": 123
}

The status code is 201 Created.

Unsubscribe

Send a DELETE to /partners-api/v1/hooks/{id} with the id you got when you subscribed. You get 200 OK back, or 404 Not Found when there is no webhook with that id on your account.

Get example payloads

GET /partners-api/v1/hooks/examples returns what we would send: the payloads of up to 5 of your most recent booked shipments, or a fixed example when you haven't booked anything yet. Handy to build your receiver before the first real shipment.

The payload

We send a POST with Content-Type: application/json to your URL, once per booked shipment. If your URL is down, we don't try again. Use List your shipments to catch up on anything you missed.

NameValueComments
Shipment ID(number)The same id you got when you created the shipment.
Pickup date(object or string)The pickup date and time, or "No pickup" if no pickup was scheduled.
Reference(string)Your own reference.
Pick-up Country(string)Country name, for example Netherlands.
Destination Country(string)Country name, for example United States.
Carrier(string)Carrier ID, for example FEDEX, DHL or UPS.
Product(string)The service, for example FedEx Economy.
Shipping costs (ex. VAT)(number)The price in euros, without VAT.
Tracking number(string)The carrier's tracking number.
Tracking number url(string)A link to track the shipment.
Import/Export(string)Import or Export.
Draft Shipment(bool)Always false for a booked shipment.
Incoterms(string)DAP, DDP, or - if none was set.
Dimensions(string)One line per parcel: length × width × height in cm, weight in kg and the number of parcels, for example 84 X 74 X 10 cm + 9.6 kg (1).
dutiable(string)yes if the shipment goes through customs with a proforma invoice, otherwise no.
description(string)The description of the contents.

Example payload

JSON
{
  "Shipment ID": 1588448,
  "Pickup date": {
    "date": "2026-11-05 12:00:00.000000",
    "timezone_type": 3,
    "timezone": "Europe/Amsterdam"
  },
  "Reference": "#123126",
  "Pick-up Country": "Netherlands",
  "Destination Country": "United States",
  "Carrier": "FEDEX",
  "Product": "FedEx Economy",
  "Shipping costs (ex. VAT)": 86.41,
  "Tracking number": "6516516533",
  "Tracking number url": "https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=6516516533&cntry_code=nl&locale=nl_NL",
  "Import/Export": "Export",
  "Draft Shipment": false,
  "Incoterms": "DAP",
  "Dimensions": "84 X 74 X 10 cm + 9.6 kg (1)",
  "dutiable": "yes",
  "description": "Awesome Product"
}

Examples

Request example - Subscribe to booked shipments

curl --location --request POST 'https://services.parcelparcel.com/partners-api/v1/hooks/subscribe' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "hookUrl": "https://example.com/parcelparcel/webhook"
}'

Request example - Get example payloads

curl --location --request GET 'https://services.parcelparcel.com/partners-api/v1/hooks/examples' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json'

Request example - Unsubscribe webhook 123

curl --location --request DELETE 'https://services.parcelparcel.com/partners-api/v1/hooks/123' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json'

Questions about webhooks? Email [email protected].