# 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: ###

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 [link](https://dash.shippify.co/automations/event/7/company) and press the button `CREATE AUTOMATION +`.

###

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

###

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

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: {% tabs %} {% tab title="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": "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}"

}

{% endtab %} {% tab title="DETAILS" %}

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

{% endtab %} {% endtabs %} ### 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 ](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63/aa83de64-adbe-4923-ba2a-e404399a50bc/1)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](https://dash.shippify.co/deliver) (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](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63/aa83de64-adbe-4923-ba2a-e404399a50bc/1) 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 with the [following table corresponding to Shippify's statuses](https://docs.shippify.co/developers/en/integration-guide/basic-processes/statuses#enlace-de-estados-con-plataforma-externa).

Request example

{% code overflow="wrap" %} ``` 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: example@shippify.co * Table with the equivalent states in Shippify and the customized payloads: Attached document Thank you in advance, Best regards, Name ``` {% endcode %}

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.shippify.co/developers/en/integration-guide/basic-processes/status-update/webhook-subscriptions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.