Postmen logo
Options
  • APC Overnight
  • Aramex
  • Asendia Germany
  • Asendia Hong Kong
  • Australia Post
  • Blue Dart
  • Bonds Couriers
  • Bpost
  • Bpost International
  • Bring
  • Canada Post
  • Canpar
  • Correos Spain
  • Courex
  • Couriers Please
  • Delhivery
  • Deutsche Post DHL
  • DHL Express
  • DHL Global Mail Asia
  • Dotzot
  • DPD Belgium
  • DPD NL
  • DPD UK
  • DPEX
  • DTDC
  • Endicia
  • Fastway Australia
  • FedEx
  • FedEx Smartpost
  • GLS Ireland
  • Grab
  • Hermesworld
  • Hong Kong Post
  • Landmark Global
  • Malaysia Post
  • Mondial Relay
  • New Zealand Post
  • Newgistics
  • Nightline
  • Ninja Van
  • onTrac
  • Pitney Bowes
  • Purolator
  • Quantium
  • S.F. Express
  • S.F. IBS
  • S.F. International
  • S.F. ISP
  • SEKO OmniParcel
  • Sendle
  • SkyNet Worldwide
  • Spanish Seur
  • StarTrack
  • Tai Wan Global Business
  • Taqbin HK
  • TIPSA
  • TNT
  • UPS
  • UPS Mail Innovation
  • USPS
  • Whistl
  • Yamato Japan
  • Yodel
  • API Resources
  • Rates
    • Calculate rates
    • List all rates
    • Retrieve rates
  • Labels
    • Create a label
    • Retrieve a label
    • List all labels
  • Manifests
    • Create a manifest
    • List all manifests
    • Retrieve a manifest
  • Cancel Labels
    • Cancel a label
    • List all cancel labels
    • Retrieve a cancel label
  • Shipper Accounts
    • Create a shipper account
    • Delete a shipper account
    • List all shipper accounts
    • Retrieve a shipper account
    • Update a shipper account credentials
    • Update a shipper account information
    • Update a shipper account
  • Bulk Downloads
    • Create a bulk download
    • List all bulk downloads
    • Retrieve a bulk download
  • Objects
  • Billing
    • Customs
      • Shipment
        • Address
          • Parcel
            • Item
              • SDKS
              • Node.js
              • PHP
              • Python
              • .NET
              • Java
              • Overview
              • Rate limit
              • Errors
              • Webhooks
              • Security
              • Contact Support

              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:

              asyncbooleanenable 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

              EventDescription
              calculate_ratesWhen POST /rates API is done
              create_a_labelWhen POST /labels API is done
              cancel_a_labelWhen POST /cancel-labels API is done
              create_a_bulk_downloadWhen POST /bulk-downloads API is done
              manifest_a_labelWhen 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.