Developers
English
English
  • πŸ‘‹Welcome
  • πŸ›’E-commerce
    • Introduction
    • Shopify
      • Functionalities
      • Steps to integrate
      • User guide
      • FAQs
    • Mercado Livre
      • Functionalities
      • Steps to integrate
      • FAQs
    • Vtex
      • Funcionalities
      • Steps to integrate
      • FAQs
    • Beetrack
      • Funcionalities
      • Steps to integrate
      • FAQs
    • Prestashop
      • Functionalities
      • Steps to integrate
      • FAQs
  • πŸ‘¨β€πŸ’»Integration Guide
    • Basic processes
      • Delivery creation
        • Dash
        • Import
        • Zapier
        • API
        • SFTP
        • Custom
      • Status update
        • Webhook subscriptions
        • Continuous Polling
        • Statuses
    • Advanced process
      • Interactive delivery tracking
      • Security
        • [2FA] Two Factor Authentication Method
        • Activate SAML SSO for a Company
  • πŸ“„Shippify Api
    • First steps
    • Deliveries
      • Delivery creation
      • Delivery Quotes
      • Get delivery information
      • Update pickup point
      • Update delivery
      • Change delivery statuses
      • Assign driver
      • Print delivery labels
      • Get a tracking link
      • Attach documents to a delivery
    • Routes
      • Create route
      • Get route information
      • Add a delivery
      • Remove a delivery
      • Break a route
      • Change the status of a route
  • πŸ“Processes
    • Create a Shippify account
Con tecnologΓ­a de GitBook
En esta pΓ‘gina
  • Process
  • Configurations
  • Create a Webhook
  • Configuring a Trigger
  • Configuring a Webhook
  • Payload
  • How to test the webhook?
  • Subscribers to errors
  • Custom configurations
  1. Integration Guide
  2. Basic processes
  3. Status update

Webhook subscriptions

AnteriorStatus updateSiguienteContinuous Polling

Última actualización hace 9 meses

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:

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:

{
    "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": ["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": "denny2@shippify.co"
        },
        "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": "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",
    "trackingUrl": "https://api.shippify.co/track/t-xyz-123?token={token}"

}
Propiedad
Detalle

id

Delivery ID

routeId

Route ID

networkId

ID of the drivers network

networkName

Name of the drivers network

cityId

ID of the pickup city

cityName

Name of the pickup city

cityLang

Language of the pickup city

jobId

The identifier of the current process, null if it doesn't have a process

blocked

Indicates if a task is blocked

companyId

Identifier of the delivery company.

companyName

Name of the delivery company.

companyPlanType

Delivery company plan (pre or post paid)

companyParentId

Parent company identifier of the delivery

companyMode

Company type: 1 basic, 2 SAAS

shipperId

Driver identifier performing the delivery

shipperMobile

Driver's phone number

type

Delivery type: flex, express or regular

vehicleCapacity

Vehicle capacity 1-5 bicycle-truck

vehicleId

Vehicle ID

price

Delivery price

insurance

Delivery insurance

scheduledStartPickingDate

Estimated start date of pickup

scheduledEndPickingDate

Estimated final date of pickup

effectivePickupDate

Acutal pickup date

arrivalPickupDate

Date when the driver arrives at the pickup point

scheduledStartDeliveryDate

Estimated start date of delivery

scheduledEndDeliveryDate

Estimated final date of delivery

effectiveDeliveryDate

Actual delivery date

arrivalDeliveryDate

Date when the driver arrives at the delivery point

creationDate

Date of when the task was created

pickupDueDate

Maximum pickup date

deliveryDueDate

Maximum delivery date

pickingPlace

Pickup information

pickingPlace.lat

Pickup point latitude

pickingPlace.lng

Pickup point longitude

pickingPlace.originalAddress

Pickup address sent by integration

pickingPlace.address

Pickup address adjusted by Google

droppingPlace

Delivery information

droppingPlace.lat

Delivery point latitude

droppingPlace.lng

Delivery point longitude

droppingPlace.originalAddress

Delivery address sent by integration

droppingPlace.address

Delivery address adjusted by Google

recipientInfo

Recipient information

senderInfo

Sender information

state

Delivery status code

tags

Delivery digital tags

items

Information about the delivery packages

items.id

Package ID

items.name

Package name

items.size

Package size

items.price

Package price

items.weight

Package weight

items.pickedUp

Indicates if a package has been collected

items.delivered

Indicates if a package has been delivered

items.scanned

Indicates if a package has been scanned

items.qty

Quantity of packages

referenceId

External identifier of the delivery

notes

String with the reason for the state change

attempts

Number of delivery attempts

countryCode

Country code

countryName

Country name

currencyCode

Currency symbol of the country

formulaId

ID of the quote applied

distance

Distance between the pickup point and the delivery point

distanceRoute

Distance between the delivery point and the previous point in the route

distanceCharged

Distance charged

totalPackagePrice

Total of packages prices

eventEntity

Entity under which the event was generated

eventDate

Date on which the event was executed

lastEventParams

Information about the author of the event

collected

Indicates whether the packages have already been collected

paid

Indicates if the delivery has been paid

notesJson

The object where the reason for the change of state is stored

notesJson.comment

General comment about the state change

notesJson.reason

Reason for the state change

notesJson.reasonId

Reason ID

itemsNumber

Total of itens in the delivery

itemsWeight

Total weight of the delivery

itemsPrice

Total price of the delivery

references

Delivery extra information

incidences

Delivery incidences

metadata

Delivery extra information

previousStatus

Previous status

eventType

Event type

eventAuthor

Information of the user who performed the event

eventCreatedAt

Date when the event was created

eventDescription

Event description

eventParams

Parameters sent to the event

status

Current status of the delivery

eventId

Event ID

images

Array of images of the delivery proofs. It can be in URL or base64 format depending on the configuration

signature

Attach the recipient's signature as a PNG image with a transparent background. It can be in URL or base64 format depending on the configuration

trackingUrl

Private delivery tracking URL

How to test the webhook?

  1. 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.

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

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: iliana@shippify.co
* Table with the equivalent states in Shippify and the customized payloads: Attached document

Thank you in advance,

Best regards,
Iliana BolaΓ±os

Create a Webhook

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 and press the button CREATE AUTOMATION +.

Configuring a Trigger

Configuring a 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 ato 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.

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

Observe the payload sent to the webhook, in this case we used a 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.

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 integrations@shippify.co with the .

πŸ‘¨β€πŸ’»
link
test endpoint
in Dash
test webhook
following table corresponding to Shippify's statuses
Webhook
AutomatizaciΓ³n
ConfiguraciΓ³n
ConfiguraciΓ³n
Webhook
ActualizaciΓ³n de estado
Webhook
Histogram
Error subscriptors
Error notification mail