Webhooks

Webhooks are a way for our system to automatically notify your software when your bookings are updated.

It is a completely optional service, however will require a receiving API on your side to catch the information that we will send back automatically.

Registering a Webhook

You can register a webhook by;

1. Logging into our customer portal and navigating to the “My Profile” section.
2. Enter your Endpoint URL that we can call, as well as a Customer API Key that we can provide with our calls (so that you know it’s us sending you information).

Your endpoint must accept information in our data format (see below for details).
Note: Parameterised URLs are not currently supported – all specific details of the data must be included in the body of the request.

Authentication

To prove that Zoom2u was the source of the request to your HTTP API endpoint, we will include a secret key in the Authorization header of each request, as an authorization token, like so:

{
  "Authorization" : "Basic B1NvaLc4ojuNmvFpUMsUsnC3YU3ECpkJ4mspmjBR",
  "Content-Type"  : "application/json"
}

You can then validate that this key is correct prior to processing the request.
Note: This value is not the same value as your API key when making requests to our API.

If this header interferes with your API’s authentication system, an alternative is to ask that we don’t provide you with a secret in the authorisation header when registering the webhook with us.
Instead, when providing us with the HTTP endpoint URL to call, you can include your own secret in the URL, either as part of the URL or as a query string parameter.
For example:
https://www.customer.com/api/zoom2ustatuschange/B1NvaLc4ojuNmvFp
OR
https://www.customer.com/api/zoom2ustatuschange?key=B1NvaLc4ojuNmvFp

Delivery Status Notifications

Each time your delivery changes status, we will make a POST request to your provided endpoint.

The body of the request includes the type of webhook (“type”), and the associated data (“data”).
The data object is of the same format as the response when getting a package’s status via the Zoom2u Customer API, so please see the documentation for that call.

Example

{
    "type": "delivery.statuschanged",
    "data": { 
        "reference": "Z2015071712345", 
        "status": "On Route to Dropoff", 
        "statusChangeDateTime": "2015-07-16T12:47:50.06Z",
        "PurchaseOrderNumber":"ABC123",
        "tracking-link":"https://track.zoom2u.com/A1B2C3D4E",
        "proofOfDeliveryPhotoUrl" : "https://zoom2u.blob.core.windows.net/uploads/PODTest.png?st=2018-11-05T08%3A41%3A23Z&se=2023-11-06T08%3A41%3A00Z&sp=rl&sv=2018-03-28&sr=b&sig=lCsUL5C7hiE2stDH0a%2FL2UPMkHPIK6uRoumQTop%2FLEI%3D", 
        "signatureUrl" : "https://zoom2u.blob.core.windows.net/uploads/PODTest.png?st=2018-11-05T08%3A41%3A23Z&se=2023-11-06T08%3A41%3A00Z&sp=rl&sv=2018-03-28&sr=b&sig=lCsUL5C7hiE2stDH0a%2FL2UPMkHPIK6uRoumQTop%2FLEI%3D"
    }
}

Testing Webhooks

Endpoint

1. 1. Blank Body Test – You can leave the body of the request blank when calling the endpoint and a sample Delivery Status Change request will be created posted to your configured webhook endpoint.

1. Request specific return content – If you want to receive specific content back as part of a test, simply post the desired content into the body of the request when you post it to our endpoint and we will send it back to you as if it had come from us initially.

1) Blank Body Test

You can test that a webhook is configured correctly by making a POST request to the following endpoint, with the Authentication variables above and an empty body content, and a sample Delivery Status Change request will be created and posted to your configured webhook endpoint.

Example response:

{
    "type": "delivery.statuschanged",
    "data": { 
        "reference": "Z2015071712345", 
        "status": "On Route to Dropoff", 
        "statusChangeDateTime": "2015-07-16T12:47:50.06Z",
        "PurchaseOrderNumber":"ABC123",
        "tracking-link":"https://track.zoom2u.com/A1B2C3D4E",
        "proofOfDeliveryPhotoUrl" : "https://zoom2u.blob.core.windows.net/uploads/PODTest.png?st=2018-11-05T08%3A41%3A23Z&se=2023-11-06T08%3A41%3A00Z&sp=rl&sv=2018-03-28&sr=b&sig=lCsUL5C7hiE2stDH0a%2FL2UPMkHPIK6uRoumQTop%2FLEI%3D", 
        "signatureUrl" : "https://zoom2u.blob.core.windows.net/uploads/PODTest.png?st=2018-11-05T08%3A41%3A23Z&se=2023-11-06T08%3A41%3A00Z&sp=rl&sv=2018-03-28&sr=b&sig=lCsUL5C7hiE2stDH0a%2FL2UPMkHPIK6uRoumQTop%2FLEI%3D"
    }
}

2) Request specific return content

If you choose to add body content to the test webhook request, that content will then be posted to your webhook endpoint, along with your secret key that identifies the source of the request as from Zoom2u.

• Your endpoint must return HTTP status code 200 (OK) as a response.
• You must still include the appropriate authorisation headers, even when sending webhook tests.

Notes

Completed delivery webhook notifications may not include a link to the proof of delivery image and signature if these have not completed uploading yet.  If you need these but they’re not yet provided, you can make a call to get the delivery’s status after a period of time (e.g. after 2 minutes), after which time the photos should have been uploaded and a URL to each will be included in the result.

Issues and troubleshooting