Webhooks allow you to subscribe to events that Shippify generates every time a delivery or route is changed. When one of those events is triggered, we'll send a HTTP POST request to the webhook's configured URL.
Webhook Setup
Declaring a Webhook
In your Shippify account, go to the left menu, choose the Automations section, look for `Push Webhook` in the left side menu and press the `CREATE AUTOMATION +` button.
Choose the rules for the execution of your automation. You need choose the scope on which the automation will work, the event that will trigger the automation and extra conditions if you need so.
Define the parameters you need for your Webhook Automation
Parameter
Description
Mandatory
Payload Key
Webhook
URL to which the event payload is going to be sent.
HTTP Method
HTTP Request Method for sending the payload
Proof of delivery
In case that the event has images attached, choose if you want to add them in your payload.
images (Array[])
HTTP Headers
Customized headers for the HTTP Request
Recipient's signature
Attach the recipient's signature as a png image with transparent background.
signature (String)
Base64 format
Images from Proof of delivery or signature are sent in base64 format. (If uncheck, then it's an url)
images/signature
(base64 Array[]/String)
Tracking Url
Includes private tracking url of the delivery.
trackingUrl (String)
In this section you can manage the URL's you declare for each of the events you want to subscribe to. You can also test your webhooks in this section and you'l receive a sample payload.
Available Webhook Events
Specification of events available for webhooks:
Name
Description
Delivery is created
Fires whenever a new delivery is created.
Delivery is in transit
Fires when a delivery has been collected and is in transit.
Delivery completed
Fires when a delivery has been delivered.
Delivery returned
Fires when a delivery has been returned to the warehouse.
Delivery canceled
Fires when a delivery was canceled by an operator.
Deliver Hold By Courier
Fires when a delivery is being hold by courier for reasons like the package couldn't be delivered. In this case you'll find the reason in the notes parameter of the payload.
Event's Payload
When one of the events listed previously is done, the webhook is executed and sends the following payload:
Delivery Created Successfully
Param
Value
Webhook
www.webhooktest.com
HTTP Method
POST
{"id":"t-xyz-123","routeId": null,"networkId": 225,"networkName": "Default-company test","jobId": null,"blocked": false,"cityId": 2,"cityName": "Guayaquil","cityLang": "es","companyId": 1,"companyName": "Shippify Inc.","companyPlanType": "postpaid","companyParentId": 1,"companyMode": 0,"shipperId": null,"type": "flex","vehicleCapacity": 2,"price": 2.75,"scheduledStartPickingDate": "2021-06-23T18:00:00.000Z","scheduledEndPickingDate": "2021-06-23T19:00:00.000Z","arrivalPickupDate": null,"scheduledStartDeliveryDate": "2021-06-23T19:00:00.000Z","scheduledEndDeliveryDate": "2021-06-24T00:00:00.000Z","arrivalDeliveryDate": null,"creationDate": "2021-06-22T20:51:27.000Z","pickupDueDate": null,"deliveryDueDate": null,"pickingPlace":{"lat":-2.1594806,"lng":-79.895742599,"originalAddress":"torres del norte, av. 9, guayaquil 090512, ecuador","address":"torres del norte, av. 9, guayaquil 090512, ecuador" },"droppingPlace":{"lat":-2.1693477,"lng":-79.8985397,"originalAddress":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador","address":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador" },"recipientInfo":{"name":"Test recipient","email":"testrecip@test.com" },"senderInfo":{"name":"Test sender","email":"testsender@test.com" },"state": 1,"tags": null,"items":[ {"name":"1","qty":1,"size":"S","price":0,"weight":0,"fragile":false,"pickedUp":false,"delivered":false } ],"referenceId": "referenceId","notes": null,"attempts": 0,"countryCode": "EC","countryName": "ECUADOR","currencyCode": "USD","formulaId": "815","cash": 0,"distance": 1.7999999523162842,"distanceRoute": 1.7999999523162842,"eventEntity": "delivery","eventDate": "2021-06-22T20:51:27+00:00","itemsNumber": 1,"itemsWeight": 0,"itemsPrice": 0,"dbId": 214280954,"eventType": "DELIVERY_CREATED_SUCCESSFULLY","eventCreatedAt": "2021-06-22 20:51:27","eventDescription": "Delivery was created successfully","status": "processing","eventId": 1624395087667}
Delivery Hold By Courier
Param
Value
Webhook
www.webhooktest.com
HTTP Method
POST
Tracking URL
{"id":"t-xyz-123","routeId":null,"networkId":25,"networkName":"Default-company test","jobId":null,"blocked":false,"cityId":2,"cityName":"Guayaquil","cityLang":"es","companyId":1,"companyName":"company test","companyPlanType":"postpaid","companyParentId":1,"companyMode":1,"shipperId":null,"shipperMobile":null,"type":"slot","vehicleCapacity":3,"vehicleId":null,"price":0,"insurance":0,"scheduledStartPickingDate":"2024-01-08T17:27:20.000Z","scheduledEndPickingDate":"2024-01-08T17:57:20.000Z","effectivePickupDate":"2024-01-08T16:33:44.000Z","arrivalPickupDate":null,"scheduledStartDeliveryDate":"2024-01-08T18:12:20.000Z","scheduledEndDeliveryDate":"2024-01-08T18:42:20.000Z","effectiveDeliveryDate":"2024-01-08T17:27:07.000Z","arrivalDeliveryDate":null,"creationDate":"2024-01-08T16:27:21.000Z","pickupDueDate":null,"deliveryDueDate":null,"pickingPlace":{"lat":-2.1594806,"lng":-79.895742599,"originalAddress":"torres del norte, av. 9, guayaquil 090512, ecuador","address":"torres del norte, av. 9, guayaquil 090512, ecuador" },"droppingPlace":{"lat":-2.1693477,"lng":-79.8985397,"originalAddress":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador","address":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador" },"recipientInfo":{"name":"Test recipient","email":"testrecip@test.com" },"senderInfo":{"name":"Test sender","email":"testsender@test.com" },"senderInfoDecoded": {"name":"Test","email":"test@test.com","phonenumber":"11111111" },"receiverInfoDecoded": {"name":"Siham","email":"","phonenumber":"" },"state":6,"tags":null,"items": [ {"id":"","uuid":"bb3ef06e-647d-412b-92d1-293de6f5ce76","name":"caixa","size":"S","price":0,"weight":0,"pickedUp":true,"delivered":true,"sid":"t-shippify2-40254_3","scanned":false,"qty":62 } ],"referenceId":"test1234","notes":"{\"reason\":\"ADDRESS NOT FOUND, NEED CHANGE\",\"reasonId\":11,\"comment\":\"test\"}","notesJson": {"reason":"ADDRESS NOT FOUND, NEED CHANGE","reasonId":11,"comment":"test" },"attempts":1,"countryCode":"EC","countryName":"ECUADOR","currencyCode":"USD","formulaId":"1234","cash":0,"distance":305.6000061035156,"distanceRoute":0,"distanceCharged":0,"totalPackagePrice":0,"eventEntity":"delivery","eventDate":"2024-01-08T20:38:55+00:00","lastEventParams": {"author": {"type":"client","id":1234,"name":"Client Name","email":"client@mail.com" },"method":"UPDATE_ROUTE_STATUS","timestamp":1704746335 },"colleted":0,"paid":0,"statusUpdateDate":null,"partial":0,"itemsNumber":62,"itemsWeight":0,"itemsPrice":0,"references": [],"incidences": [],"cityDepartment":null,"metadata": {"previousStatus":"processing" },"previousStatus":"processing","dbId":948182101,"eventType":"DELIVERY_HOLD_BY_COURIER","eventAuthor": {"type":"client","id":1234,"name":"Client Name","email":"client@mail.com" },"eventCreatedAt":"2024-01-08 20:38:55","eventDescription":"Delivery is hold by courier (previous status was completed)","eventParams":"{\"method\":\"UPDATE_ROUTE_STATUS\"}","status":"hold_by_courier","eventId":1704746335377,"trackingUrl":"https://api.shippify.co/track/t-xyz-123?token={token}"}
Delivery Completed
Param
Value
Webhook
www.webhooktest.com
HTTP Method
POST
Proof of delivery
Recipient's signature
{"id":"t-xyz-123","routeId":null,"networkId":25,"networkName":"Default-company test","jobId":null,"blocked":false,"cityId":2,"cityName":"Guayaquil","cityLang":"es","companyId":1,"companyName":"company test","companyPlanType":"postpaid","companyParentId":1,"companyMode":1,"shipperId":null,"shipperMobile":null,"type":"slot","vehicleCapacity":3,"vehicleId":null,"price":0,"insurance":0,"scheduledStartPickingDate":"2024-01-08T17:27:20.000Z","scheduledEndPickingDate":"2024-01-08T17:57:20.000Z","effectivePickupDate":"2024-01-08T16:33:44.000Z","arrivalPickupDate":null,"scheduledStartDeliveryDate":"2024-01-08T18:12:20.000Z","scheduledEndDeliveryDate":"2024-01-08T18:42:20.000Z","effectiveDeliveryDate":"2024-01-08T17:27:07.000Z","arrivalDeliveryDate":null,"creationDate":"2024-01-08T16:27:21.000Z","pickupDueDate":null,"deliveryDueDate":null,"pickingPlace":{"lat":-2.1594806,"lng":-79.895742599,"originalAddress":"torres del norte, av. 9, guayaquil 090512, ecuador","address":"torres del norte, av. 9, guayaquil 090512, ecuador" },"droppingPlace":{"lat":-2.1693477,"lng":-79.8985397,"originalAddress":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador","address":"san marino shopping, av. francisco de orellana, guayaquil 090512, ecuador" },"recipientInfo":{"name":"Test recipient","email":"testrecip@test.com" },"senderInfo":{"name":"Test sender","email":"testsender@test.com" },"senderInfoDecoded": {"name":"Test sender","email":"testsender@test.com" },"receiverInfoDecoded": {"name":"Test recipient","email":"testrecip@test.com" },"state":7,"tags":null,"items": [ {"id":"","uuid":"bb3ef06e-647d-412b-92d1-293de6f5ce76","name":"caixa","size":"S","price":0,"weight":0,"pickedUp":true,"delivered":true,"sid":"t-shippify2-40254_3","scanned":false,"qty":62 } ],"referenceId":"test1234","notes":"{\"comment\":\"test\"}","attempts":0,"countryCode":"EC","countryName":"ECUADOR","currencyCode":"USD","formulaId":"1234","cash":0,"distance":305.6000061035156,"distanceRoute":0,"distanceCharged":0,"totalPackagePrice":0,"eventEntity":"delivery","eventDate":"2024-01-08T17:27:08+00:00","lastEventParams": {"author": {"type":"client","id":2534,"name":"Denny K. Saas","email":"denny2@shippify.co" },"method":"UPDATE_ROUTE_STATUS","timestamp":1704734827 },"colleted":0,"paid":0,"statusUpdateDate":null,"partial":0,"notesJson": {"comment":"test" },"itemsNumber":62,"itemsWeight":0,"itemsPrice":0,"references": [],"incidences": [],"cityDepartment":null,"metadata": {"previousStatus":"processing" },"previousStatus":"processing","dbId":948182094,"eventType":"DELIVERY_COMPLETED","eventAuthor": {"type":"client","id":2534,"name":"Denny K. Saas","email":"denny2@shippify.co" },"eventCreatedAt":"2024-01-08 17:27:07","eventDescription":"Delivery was completed (previous status was processing)","eventParams":"{\"method\":\"UPDATE_ROUTE_STATUS\"}","status":"completed","eventId":1704734828038,"images": ["https://cdn.dev.shippify.co/delivery-files/77030821377477563003dde3ce5.jpg"],"signature":"https://cdn.dev.shippify.co/delivery-files/16839098636794LPh1Zd7S5Goc9BvmQyG7BpT6asb.png"}
