10. Webhooks

# 10.A Add subscription

# 10.A.1 Overview

Use this endpoint to subscribe to an event in our API. Upon success an HTTP/1.1 200 OK with subscription ids is returned. You must use HTTPS for callback because it's secure and tamper-proof. You can only have one webhook of each type at a time for a shop so adding the same webhook overwrites any existing one. We always send the webhook to a URL with lowercase characters. Therefore, it is necessary to use lowercase characters in the URL of the webhook call.

We currently have three available hooks: shipment_status_change, shipment_label_created and order_status_change:

• shipment_status_change: Whenever the shipment_status of a shipment changes, this webhook will send you an update with the new value. We will not send an update with a status 1.
• shipment_label_created: When a label is created asynchronously (for example when creating shipments using accept header application/vnd.shipment_label+json;charset=utf-8), this webhook will send you a message with the URL of the label.
• order_status_change: Whenever the order_status of an order changes, this webhook will send you an update with the new value.

# 10.A.2 Reference

# 10.A.3 Example

Request

POST https://api.myparcel.nl/webhook_subscriptions HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY
Content-Type:application/json; charset=utf-8

{
  "data": {
    "webhook_subscriptions": [
      {
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

Response

{
  "data": {
    "ids": [
      {
        "id": 3
      }
    ]
  }
}

# 10.B Get subscriptions

# 10.B.1 Overview

Use this endpoint to fetch your active webhook subscriptions. Upon success an HTTP/1.1 200 OK with an array of Subscription objects is returned.

# 10.B.2 Reference

# 10.B.3 Parameters

id
Data type: integer
This is the subscription id. You can specify multiple subscription ids by semicolon separating them on the URI.

# 10.B.4 Example

Request

GET https://api.myparcel.nl/webhook_subscriptions/12 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY

Response

{
  "data": {
    "webhook_subscriptions": [
      {
        "id": 123,
        "hook": "shipment_status_change",
        "url": "https://seoshop.nl/myparcel/notifications"
      }
    ]
  }
}

# 10.C Delete subscription

# 10.C.1 Overview

Use this endpoint to delete webhook subscriptions. You can specify multiple subscription ids by semicolon separating them on the URI. Upon delete an <Http code=204 /> is returned.

# 10.C.2 Reference

# 10.C.3 Parameters

id
Data type: integer .id
The id of the subscription to delete. You can specify multiple subscriptions by semicolon separating them.

# 10.C.4 Example

Request

DELETE https://api.myparcel.nl/webhook_subscriptions/1 HTTP/1.1
User-Agent: CustomApiCall/2
Authorization: bearer BASE64_ENCODED_API_KEY

Response