Webhooks
In order to get the best performance, you can use webhooks to receive the push update when the API is made asynchronously:
- Calculate Rate
- Create Label
- Cancel Label
- Create Bulk Download
- Manifest
How to setup the Webhooks
You can follow this to setup the webhooks in your account.
Receiving a webhook notification
When making Postmen API request, you can give a parameter async=true to receive a webhook notification when Postmen has the response ready. In order to receive a webhook, you need to enable the webhook setting first.
In the API request, you have to:
async | boolean | enable async model or not |
Webhook data is sent as JSON in the POST request body.
The webhook envelope contains:
{
"event": "calculate_rates",
"date_time": "2016-09-26T07:15:30+00:00",
"meta": {
// meta and body, are same as our API envelope
},
"data": {
// https://docs.postmen.com/overview.html#the-envelope
}
}
Events
Event | Description |
---|---|
calculate_rates | When POST /rates API is done |
create_a_label | When POST /labels API is done |
cancel_a_label | When POST /cancel-labels API is done |
create_a_bulk_download | When POST /bulk-downloads API is done |
manifest_a_label | When POST /manifests API is done |
Example
Calculated rate webhook
{
"event": "calculate_rates",
"date_time": "2016-09-26T07:15:30+00:00",
"meta": {
"code": 4713,
"message": "All or partial failed in rate request.",
"details": [],
"retryable": false
},
"data": {
"created_at": "2016-09-26T07:15:26+00:00",
"id": "xxxxxx-3b12-4376-bc3d-33333333",
"updated_at": "2016-09-26T07:15:30+00:00",
"status": "calculated",
"rates": [
{
"shipper_account": {
"id": "yyyyyy-1b7a-45da-8e1f-67898736567",
"slug": "fedex",
"description": "fedex testing account"
},
"service_type": null,
"service_name": null,
"pickup_deadline": null,
"booking_cut_off": null,
"delivery_date": null,
"transit_time": null,
"error_message": null,
"info_message": null,
"charge_weight": null,
"total_charge": null,
"detailed_charges": []
}
]
}
}
Retry Webhooks
Postmen sent the events for each webhook URL with POSTs request. If the webhook URL doesn't return a 200 HTTP response code, that POST request will be re-attempted up to 14 times in increasing intervals: 2^number_of_fail x 30s
e.g.
If the attempt fail, Postmen will retry the 2nd attempt 30s later.
If the 5th attempts fail, Postmen retry the 6th attempt 960s later
If the 14th attempts fail, Postmen retry not send out that webhook any more.
Securing Webhooks
We currently support either HTTP or HTTPS urls, so you can have security by using an SSL-enabled url. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private, our best suggestion is to simply include a secret key in the URL that your provide and check the secret GET parameter in your scripts.