EasyShip webhooks

What is a webhook?

A WebHook is an HTTP callback: an HTTP POST that occurs when something happens. A web application implementing WebHooks will POST a message to a URL when certain things happen.

Configuring your account

In order to use EasyShip webhooks your partner account must either be configured with a webhook endpoint or you must specify a webhook URL in your request for an EasyShip session. Please contact support to add the endpoint to your partner account.

EasyShip webhook events

There are currently four types of EasyShip events that trigger webhook calls:

label.purchased
label.refunded
label.failed
label.refund.failed

When one of these events occurs, an event JSON payload is delivered to the partner's webhook endpoint. Here's an example of a "label.purchased" request and its payload:

Example payload

Here's an example of a "label.purchased" webhook payload:

Example label.purchased event payload

{
    "event": {
        "guid": "evt_32b058552dc5ce257fa73bf1492073ac",
        "created_at": "2015-01-12T17:46:41Z",
        "event_type": "label.purchased",
        "data": {
            "shipment": {
                "order_number": "312444-4708",
                "refund_url": "https://app.shippingeasy.com/easyship/shipments/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2/cancellations",
                "tracking_url": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=040XXXXXXXXXXX",
                "tracking_number": "040XXXXXXXXXXX",
                "ship_date": "2015-06-25",
                "carrier": "USPS",
                "status": "purchased",
                "carrier_service": "Priority Mail (2-3 days)",
                "label_api_url": "https://app.shippingeasy.com/partners/api/labels/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2",
                "partner_user": {
                    "external_identifier": "XXX-10813",
                    "name": "Acme Store",
                    "email": "[email protected]"
                }
            }
        }
    }
}

Note that to use the label_api_url, you must sign the GET request with your Partner API Secret. The URL must also include your Partner API Key and a current timestamp, as described here. An example:

HTML

https://app.shippingeasy.com/partners/api/labels/6d6a50c636f3ac1b8dcacf97ffb744c73466289a2540d1eadc5ee429efe9d064ada2b3c1b836fc4478125abcc435a7c8cd9877024af83bbc05d106e68b24f5a2?api_key=355d42dcd5fb4772ff891a531282ff0d&api_signature=627e545b519e3655f79176393686ac7e225fecdcdfa507db4a5632f9d5072d43&api_timestamp=1437749309

Delivery attempts

The webhook system will make up to 8 delivery attempts over the course of 36 hours, backing of an additional hour between each attempt until all are exhausted. This helps improve event deliverability by handling brief outages or hiccups on the partner's endpoint.

Signed requests

All webhook requests include an API signature calculated using the partner's api key and secret. Though optional, it is highly recommended that the partner use the signature to authenticate the webhook request and ensure it actually came from ShippingEasy.