Webhook subscriptions

Process

This method involves subscribing one of your endpoints to our webhook. This way, every time there's a change of state within the platform, we'll call that endpoint to inform you of the change. Within this endpoint, you need to interpret the payload sent by us and update the state within your system.

Configurations

For this step, you should have your table ready with the equivalent states of Shippify in your platform. If you don't have it yet, access this link to create it. For each state that you need to update in your platform, you'll have to create a separate webhook following the given steps:

In your Shippify account, go to the left menu, select the Automations section, look for Send Webhook in the left sidebar menu, or enter directly through this link and press the button CREATE AUTOMATION +.

Choose the rules for executing your automation. You need to select the scope in which the automation will work, the event that will trigger the automation, and any additional conditions if needed.

For our case, the entity we will choose is a delivery, and the event is the state you want the update to be sent. In case your table defines a delivery issue reason or an additional label, you should add this data as conditions.

In this step, you need to add the information of the endpoint where the notifications will be sent and configure if you want to send extra data.

Define the parameters you need for your Webhook Automation.

Parameter	Description	Mandatory
Webhook	URL to which the event payload will be sent.
Method HTTP	Request method HTTP to send the payload.
Delivery proof	In case the event has attached images, choose whether you want to add them to your payload as images. (Array[]).
HTTP Headers	Custom headers for the HTTP request.
Recipient's signature	Attach the recipient's signature as a PNG image with a transparent background. Add it to the payload as "signature". (String)
Base64 format	The proof of delivery or signature images are sent in base64 format. (If not marked, then it's a URL)
Tracking URL	Include private tracking URL of the delivery. You will find it in the payload as trackingUrl. (String)

After configuring it, click on "create", optionally, you can give it a name. From that moment on, each time the events and conditions are met, we will call your endpoint to notify the event.

Payload

The payload sent to the webhook is extensive and contains a lot of information. Here's the meaning of each property:

JSON

{
    "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": "[e-mail]"
    },
    "senderInfo":{
      "name": "Test sender",
      "email": "[e-mail]"
    },
    "senderInfoDecoded": {
        "name": "Test sender",
        "email": "[e-mail]"
    },
    "receiverInfoDecoded": {
        "name": "Test recipient",
        "email": "[e-mail]"
    },
    "state": 7,
    "tags": ["fragile"],
    "items": [
        {
            "id": "Box-12",
            "uuid": "bb3ef06e-647d-412b-92d1-293de6f5ce76",
            "name": "box",
            "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": "[e-mail]"
        },
        "method": "UPDATE_ROUTE_STATUS",
        "timestamp": 1704734827
    },
    "colleted": 0,
    "paid": 0,
    "statusUpdateDate": null,
    "partial": 0,
    "notesJson": {
        "reason": "ADDRESS NOT FOUND, NEED CHANGE",
        "reasonId": 11,
        "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": "[e-mail]"
    },
    "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",
    "trackingUrl": "https://api.shippify.co/track/t-xyz-123?token={token}"

}

DETAILS

How to test the webhook?

Once the automation is created, you can proceed to test it. If you do not yet have an endpoint ready to receive updates, you can use a test endpoint to test the webhook configuration and see the payload. For this example, we will configure the webhook automation to send the update when the delivery changes to "Completed" status.

1. Create a delivery in Dash (if you have already created one you can skip this step).

2. Change the status as appropriate for the automation, in this case, we will change the status to Completed because that is how we configured our test automation.

3. Observe the payload sent to the webhook, in this case we used a test webhook so we can see the payload sent, in case you already have an endpoint configured to receive notifications you can place a log to identify that the call was made.

Within the automation, you can see the failed and successful executions of the automation along with the identifier of the associated delivery. In this case, we have a successful execution for delivery t-pruaas-5104.

Subscribers to errors

Once the webhook is successfully configured, error subscriptions can be activated. Here you can register one or more emails in which alerts will be sent whenever a notification fails to be sent or the endpoint responds with an error.

Custom configurations

If you need to use the webhook but require receiving a different payload than the previous one, you must request it by email, attaching the payload you want to receive for each state, and send it to [e-mail] with the following table corresponding to Shippify's statuses.

Request example

Good morning,

I would like to update the orders in my platform using a webhook with a customized payload.

* Email of my company in Shippify: [e-mail]
* Table with the equivalent states in Shippify and the customized payloads: Attached document

Thank you in advance,

Best regards,
Iliana Bolaños