{"_id":"552d359b3e1c280d00f76385","parentDoc":null,"user":"5436a1afb7cf0e1c0020d9ca","__v":9,"category":{"_id":"54cc2149380ecd0d00ca18ae","__v":2,"pages":["54cc2149380ecd0d00ca18d2","54cc2149380ecd0d00ca18d3","54cc2149380ecd0d00ca18d4","54cc2149380ecd0d00ca18d5","555236587988e10d003452e9"],"project":"5436a1e1d0ffee0e00f18f8c","version":"54cc2148380ecd0d00ca18aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-09T15:31:35.377Z","from_sync":false,"order":3,"slug":"easyship-widget","title":"EasyShip Widget"},"project":"5436a1e1d0ffee0e00f18f8c","version":{"_id":"54cc2148380ecd0d00ca18aa","__v":2,"forked_from":"5436a1e1d0ffee0e00f18f8f","project":"5436a1e1d0ffee0e00f18f8c","createdAt":"2015-01-31T00:26:48.753Z","releaseDate":"2015-01-31T00:26:48.753Z","categories":["54cc2149380ecd0d00ca18ab","54cc2149380ecd0d00ca18ac","54cc2149380ecd0d00ca18ad","54cc2149380ecd0d00ca18ae","54cc2149380ecd0d00ca18af","54cc2149380ecd0d00ca18b0","54cc2149380ecd0d00ca18b1","54cc2149380ecd0d00ca18b2","54cc2149380ecd0d00ca18b3","552f29ca633a5b0d00e99d09"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-14T15:43:23.111Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"What is a webhook?\"\n}\n[/block]\nA 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuring your account\"\n}\n[/block]\nIn 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](https://shippingeasy.readme.io/docs/partners-api-sessions). Please contact support to add the endpoint to your partner account.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"EasyShip webhook events\"\n}\n[/block]\nThere are currently four types of EasyShip events that trigger webhook calls:\n\nlabel.purchased\nlabel.refunded\nlabel.failed\nlabel.refund.failed\n\nWhen 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:\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example payload\"\n}\n[/block]\nHere's an example of a \"label.purchased\" webhook payload:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"event\\\": {\\n        \\\"guid\\\": \\\"evt_32b058552dc5ce257fa73bf1492073ac\\\",\\n        \\\"created_at\\\": \\\"2015-01-12T17:46:41Z\\\",\\n        \\\"event_type\\\": \\\"label.purchased\\\",\\n        \\\"data\\\": {\\n            \\\"shipment\\\": {\\n                \\\"order_number\\\": \\\"312444-4708\\\",\\n                \\\"refund_url\\\": \\\"https://app.shippingeasy.com/easyship/shipments/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2/cancellations\\\",\\n                \\\"tracking_url\\\": \\\"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=040XXXXXXXXXXX\\\",\\n                \\\"tracking_number\\\": \\\"040XXXXXXXXXXX\\\",\\n                \\\"ship_date\\\": \\\"2015-06-25\\\",\\n                \\\"carrier\\\": \\\"USPS\\\",\\n                \\\"status\\\": \\\"purchased\\\",\\n                \\\"carrier_service\\\": \\\"Priority Mail (2-3 days)\\\",\\n                \\\"label_api_url\\\": \\\"https://app.shippingeasy.com/partners/api/labels/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2\\\",\\n                \\\"partner_user\\\": {\\n                    \\\"external_identifier\\\": \\\"XXX-10813\\\",\\n                    \\\"name\\\": \\\"Acme Store\\\",\\n                    \\\"email\\\": \\\"merchant:::at:::test-store.com\\\"\\n                }\\n            }\\n        }\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Example label.purchased event payload\"\n    }\n  ]\n}\n[/block]\nNote 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](http://shippingeasy.readme.io/docs/authentication-signing-requests). An example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://app.shippingeasy.com/partners/api/labels/6d6a50c636f3ac1b8dcacf97ffb744c73466289a2540d1eadc5ee429efe9d064ada2b3c1b836fc4478125abcc435a7c8cd9877024af83bbc05d106e68b24f5a2?api_key=355d42dcd5fb4772ff891a531282ff0d&api_signature=627e545b519e3655f79176393686ac7e225fecdcdfa507db4a5632f9d5072d43&api_timestamp=1437749309\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Delivery attempts\"\n}\n[/block]\nThe 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.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Signed requests\"\n}\n[/block]\nAll 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.","excerpt":"","slug":"easyship-webhooks","type":"basic","title":"EasyShip webhooks"}
[block:api-header] { "type": "basic", "title": "What is a webhook?" } [/block] 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. [block:api-header] { "type": "basic", "title": "Configuring your account" } [/block] 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](https://shippingeasy.readme.io/docs/partners-api-sessions). Please contact support to add the endpoint to your partner account. [block:api-header] { "type": "basic", "title": "EasyShip webhook events" } [/block] 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: [block:api-header] { "type": "basic", "title": "Example payload" } [/block] Here's an example of a "label.purchased" webhook payload: [block:code] { "codes": [ { "code": "{\n \"event\": {\n \"guid\": \"evt_32b058552dc5ce257fa73bf1492073ac\",\n \"created_at\": \"2015-01-12T17:46:41Z\",\n \"event_type\": \"label.purchased\",\n \"data\": {\n \"shipment\": {\n \"order_number\": \"312444-4708\",\n \"refund_url\": \"https://app.shippingeasy.com/easyship/shipments/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2/cancellations\",\n \"tracking_url\": \"https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=040XXXXXXXXXXX\",\n \"tracking_number\": \"040XXXXXXXXXXX\",\n \"ship_date\": \"2015-06-25\",\n \"carrier\": \"USPS\",\n \"status\": \"purchased\",\n \"carrier_service\": \"Priority Mail (2-3 days)\",\n \"label_api_url\": \"https://app.shippingeasy.com/partners/api/labels/c14e16c3ff6fdf664c5e1cca01e60fbb9b2ae8c50ad399d13f4b6f3b2e0895c21edc59ca2f9a2aaa2\",\n \"partner_user\": {\n \"external_identifier\": \"XXX-10813\",\n \"name\": \"Acme Store\",\n \"email\": \"merchant@test-store.com\"\n }\n }\n }\n }\n}", "language": "json", "name": "Example label.purchased event payload" } ] } [/block] 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](http://shippingeasy.readme.io/docs/authentication-signing-requests). An example: [block:code] { "codes": [ { "code": "https://app.shippingeasy.com/partners/api/labels/6d6a50c636f3ac1b8dcacf97ffb744c73466289a2540d1eadc5ee429efe9d064ada2b3c1b836fc4478125abcc435a7c8cd9877024af83bbc05d106e68b24f5a2?api_key=355d42dcd5fb4772ff891a531282ff0d&api_signature=627e545b519e3655f79176393686ac7e225fecdcdfa507db4a5632f9d5072d43&api_timestamp=1437749309", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Delivery attempts" } [/block] 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. [block:api-header] { "type": "basic", "title": "Signed requests" } [/block] 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.