11. Webhook Object Definitions

# 11.A Subscription

# 11.A.1 Overview

This object contains an event and a callback URL that will receive notifications.

id
Data type: integer
Required: No.
The id of the webhook subscription.

hook
Data type: string (shipment_label_created or shipment_status_change)
Required: Yes.
The event from which you want to receive notifications.

url
Data type: string
Required: Yes.
The callback URL on which to receive notifications. The URL protocol must be https.

account_id
Data type: integer
Required: No.
The ID of the account to which this subscription belongs.

shop_id
Data type: integer
Required: No.
The ID of the shop to which this subscription belongs.

# 11.A.2 Examples

POST Example

{
  "hook": "shipment_status_change",
  "url": "https://seoshop.nl/myparcel/notifications"
}

GET Example

{
  "id": 79798,
  "account_id": 126594,
  "shop_id": 39399,
  "hook": "shipment_status_change",
  "URL": "https://seoshop.nl/myparcel/notifications"
}

The above is an example of the Webhook Object. However, you receive the following content:

{
  "data": {
    "webhook_subscriptions": [
      {
        "id": 79798,
        "account_id": 126594,
        "shop_id": 39399,
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

# 11.B ShipmentStatusChangeEvent

# 11.B.1 Overview

This object contains the shipment status change event. This object is sent to the callback URL specified in the Subscription object whenever a shipment status changes.

shipment_id
Data type: string
This is the shipment id.

account_id
Data type: integer
This is the account id to which the shipment belongs.

shop_id
Data type: integer
This is the shop to which the shipment belongs.

status
Data type: shipment_status
The shipment status.

barcode
Data type: string
This is the shipment barcode.

shipment_reference_identifier
Data type: string
This is the shipment reference identifier, which can contain the webshop order reference.

order_id
Data type: string
This is the MyParcel order UUID to which the shipment belongs. Only present if the shipment is part of an Order.

# 11.B.2 Reference

We send the following headers to your environment:

# 11.B.3 Example

{
  "shipment_id": "25482412",
  "account_id": 7003,
  "shop_id": 1897,
  "status": 2,
  "barcode": "3SMYPA749883621",
  "shipment_reference_identifier": "Bol.com nr: 4161412988",
  "order_id": "db610547-7434-4f6d-9e13-178b686a94d6"
}

The above is an example of the ShipmentStatusChangeEvent Object. However, the following notification is sent to your callback URL:

{
  "data": {
    "hooks": [
      {
        "shipment_id": "25482412",
        "account_id": 7003,
        "shop_id": 1897,
        "status": 2,
        "barcode": "3SMYPA749883621",
        "shipment_reference_identifier": "Bol.com nr: 4161412988",
        "order_id": "db610547-7434-4f6d-9e13-178b686a94d6"
      }
    ]
  }
}

# 11.C ShipmentLabelCreated

# 11.C.1 Overview

This object contains the shipment label created event. This object is sent to the callback URL specified in the Subscription object when a label is created asynchronously (for example when creating shipments using accept header application/vnd.shipment_label+json;charset=utf-8).

status
Data type: webhook_status

shipment_ids
Data type: array of integer

printer_identifier
Data type: [printer_identifier]

pdf
Data type: string
This field contains a URL that leads to a PDF.

# 11.C.2 Reference

We send the following headers to your environment:

# 11.C.3 Example

{
  "status": "success",
  "shipment_ids": [15001826],
  "printer_identifier": "YOUR_PRINTER_ID",
  "pdf": "https://api.myparcel.nl/pdfs/f569bc5a247fcec09d6a8cba16ff7629ca8062f3"
}

{
  "status": "failed",
  "shipment_ids": [15001820],
  "printer_identifier": "",
  "pdf": "",
  "reason": "payment required"
}

The above is an example of the ShipmentLabelCreated Object. However, the following notification is sent to your callback URL:

{
  "data": {
    "hooks": [
      {
        "status": "success",
        "shipment_ids": [15001826],
        "printer_identifier": "YOUR_PRINTER_ID",
        "pdf": "https://api.myparcel.nl/pdfs/f569bc5a247fcec09d6a8cba16ff7629ca8062f3"
      }
    ]
  }
}

# 11.D SubscriptionIds

This object contains an array of SubscriptionId objects.

ids
Data type: array of SubscriptionId objects.
Required: n/a.
array of SubscriptionId objects.

# 11.E SubscriptionId

id
Data type: integer
Required: n/a.
Subscription .id