HomeAPI Reference10. Webhooks

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.

You can test webhooks with Webhook Tester. You can also use the backoffice to update the webhook URL.

10.A.2 Reference

URIhttps://api.myparcel.nl/webhook_subscriptions
MethodsPOST
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
Content-type: application/json; charset=utf-8
URI parametersNone.
Query parametersNone.
Request bodyarray of Subscription objects.
ResponseHTTP/1.1 200 OK
Response bodySubscriptionIds
Error responseHTTP/1.1 4xx < MESSAGE >
Error response bodyError

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

HTTP 200 OK
{
  "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

URIhttps://api.myparcel.nl/webhook_subscriptions/
MethodsGET
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
ResponseHTTP/1.1 201 OK
Response bodyarray of Subscription objects
Error responseHTTP/1.1 4xx < MESSAGE >
Error response bodyError

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

HTTP 200 OK
{
  "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

URIhttps://api.myparcel.nl/webhook_subscriptions/id[;id]
MethodsDELETE
Required request headersAuthorization: basic BASE64(API_KEY)
User-Agent: CustomApiCall/2
Content-type: application/json; charset=utf-8
URI parametersid = Subscription.id.
Query parametersNone.
Request bodyNone.
ResponseHTTP/1.1 204 No Content
Response bodyNone.
Error responseHTTP/1.1 4xx < MESSAGE >
Error response bodyError

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

HTTP 204 No Content
Edit this page
Last updated: 
Contributors Peter-MyParcel