> For the complete documentation index, see [llms.txt](https://docs.shippify.co/developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shippify.co/developers/guia-de-integracion/procesos-basicos/actualizacion-de-estados/suscripciones-a-webhooks.md).

# Suscripciones a webhooks

## Proceso

Este método implica subscribir un endpoint suyo a nuestro webhook, de este modo cada que exista una cambio de estado dentro de la plataforma, nosotros llamaremos a ese endpoint para informarle del cambio. Dentro de este endpoint usted tiene que interpretar el payload enviado por nosotros y realizar la actualización de estado dentro de su sistema.

<figure><img src="/files/bkHCL2OHUxZCIcxnYJqj" alt=""><figcaption><p>Webhook</p></figcaption></figure>

## Configuración

Para este punto debes tener lista tu tabla con los estados equivalentes de shippify en tu plataforma, si no lo tienes accede a este [link](/developers/guia-de-integracion/procesos-basicos/actualizacion-de-estados/estados.md#enlace-de-estados-con-plataforma-externa) para elaborarla. Por cada estado que necesites actualizar en tu plataforma vas a tener que crear un webhook diferente siguiendo los pasos dados:

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FhWClN6JV7cXBYhVcj1pR%252Fimage.png%3Falt=media%26token=9350f3ef-438f-4f9b-98d7-a5aee121a635&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=81abe1a352ece75b5a48782ac8c87cbe6a162f25f58f894d8bd446f069ab2e95" alt="" data-size="line">Crear un Webhook <a href="#declarar-un-webhook" id="declarar-un-webhook"></a>

En tu cuenta de Shippify, ve al menú de la izquierda, elige la sección de Automatizaciones, busca `Enviar Webhook` en el menú lateral izquierdo o ingresa directamente por este [link](https://dash.shippify.co/automations/event/7/company) y pulsa el botón `CREAR AUTOMATIZACIÓN +`.

<figure><img src="/files/KksWx82dk2rMiOgRssbf" alt=""><figcaption><p>Automatización</p></figcaption></figure>

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FgCi3BsNsKouEfcSbJVuf%252Fimage.png%3Falt=media%26token=fa47692d-7d0a-44fb-bdb4-0d3df3b8cd9b&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=82ce46542d7384ac869937c9f28ab968f7d0540f5b358cf5cd02b4e0862be9c7" alt="" data-size="line">Configurar Trigger

Elige las reglas para la ejecución de tu automatización. Tienes que elegir el ámbito en el que funcionará la automatización, el evento que activará la automatización y condiciones adicionales si lo necesitas.

Para nuestro caso, la entidad que vamos a elegir es `una entrega` y el evento es el estado que deseas que se envíe la actualización. En el caso que en tu tabla tengas definido un motivo de problema de entrega o una etiqueta adicional, debes añadir estos datos como condiciones.

<figure><img src="/files/zjXTktG6pT0l6MKokfsH" alt=""><figcaption><p>Configuración</p></figcaption></figure>

### <img src="https://docs.shippify.co/~gitbook/image?url=https:%2F%2F4161681308-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F5jRdo0cXdFHp6c7ZKdof%252Fuploads%252FPEAUzv8vkHU8gh7zofEU%252Fimage.png%3Falt=media%26token=72874e0e-a741-4087-bf43-67ad7fef7ed5&#x26;width=40&#x26;dpr=4&#x26;quality=100&#x26;sign=6227089c582e7089a98f4281c1da3b6ab1c7f502816c725f7da3e8568c3eebc7" alt="" data-size="line">Configurar Webhook

En este paso tienes que añadir la información del endpoint donde van a llegar las notificaciones y configurar si quieres que se envien datos extras.

<figure><img src="/files/rXUmFegpw1tMYN0yFcBW" alt=""><figcaption><p>Configuración</p></figcaption></figure>

Define los parámetros que necesitas para tu Automatización de Webhook.

<table><thead><tr><th width="211">Parámetro</th><th>Descripción</th><th width="144" data-type="checkbox">Obligatorio</th></tr></thead><tbody><tr><td>Webhook</td><td>URL a la que se enviará el payload del evento.</td><td>true</td></tr><tr><td>Método HTTP</td><td>Método de solicitud HTTP para enviar el payload.</td><td>true</td></tr><tr><td>Prueba de entrega</td><td>En caso de que el evento tenga imágenes adjuntas, elige si deseas añadirlas en tu payload como <code>images</code><em><mark style="color:blue;">(Array[])</mark></em>. </td><td>false</td></tr><tr><td>HTTP Headers</td><td>Headers personalizados para la solicitud HTTP.</td><td>false</td></tr><tr><td>Firma del destinatario</td><td>Adjunta la firma del destinatario como imagen png con fondo transparente. Lo añade al payload como <code>signature</code> <em><mark style="color:blue;">(String)</mark></em></td><td>false</td></tr><tr><td>Formato Base64</td><td>Las imágenes de la prueba de entrega o firma se envían en formato base64. (Si no se marca, entonces es una url)</td><td>false</td></tr><tr><td>URL de seguimiento</td><td>Incluye URL privada de seguimiento de la entrega. Lo encontrarás en el payload como <code>trackingUrl</code> <em><mark style="color:blue;">(String)</mark></em> </td><td>false</td></tr></tbody></table>

Luego de configurarlo le das en crear, opcionalmente podras añadirle un nombre. Desde ese momento cada vez que se cumplan los eventos y condiciones, llamaremos a tu endpoint notificando el evento.

### Payload

El payload que se envía al webhook es extenso y con mucha información, a continuación de mostraremos el significado de cada propiedad.

{% tabs %}
{% tab title="JSON" %}

<pre class="language-json" data-full-width="true"><code class="lang-json"><strong>{
</strong>    "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": ["delicado"],
    "items": [
        {
            "id": "Caja-12",
            "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": 1,
            "name": "Author example",
            "email": "example@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": "Author test",
        "email": "example@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/7703082ce5.jpg"],
    "signature": "https://cdn.dev.shippify.co/delivery-files/1683LPh1Zdsb.png",
    "trackingUrl": "https://api.shippify.co/track/t-xyz-123?token={token}"

}
</code></pre>

{% endtab %}

{% tab title="DETALLE" %}

<table><thead><tr><th width="262">Propiedad</th><th>Detalle</th></tr></thead><tbody><tr><td>id</td><td>Identificador de la entrega</td></tr><tr><td>routeId</td><td>Identificador de la ruta</td></tr><tr><td>networkId</td><td>Identificador de la red de conductores</td></tr><tr><td>networkName</td><td>Nombre de la red de conductores</td></tr><tr><td>cityId</td><td>Identificador de la ciudad de recolección</td></tr><tr><td>cityName</td><td>Nombre de la ciudad de recolección</td></tr><tr><td>cityLang</td><td>Idioma de la ciudad de recolección</td></tr><tr><td>jobId</td><td>Identificador del proceso actual, null si no tiene proceso</td></tr><tr><td>blocked</td><td>Indica si la tarea esta bloqueada</td></tr><tr><td>companyId</td><td>Identificador de la compañía de la entrega</td></tr><tr><td>companyName</td><td>Nombre de la compañía de la entrega</td></tr><tr><td>companyPlanType</td><td>Plan de la compañía de la entrega (pre o post pago)</td></tr><tr><td>companyParentId</td><td>Identificador de la compañía padre de la entrega</td></tr><tr><td>companyMode</td><td>Tipo de compañía: 1 basica, 2 saas</td></tr><tr><td>shipperId</td><td>Identificador del conductor que realiza la entrega</td></tr><tr><td>shipperMobile</td><td>Número telefónico del conductor que realiza la entrega</td></tr><tr><td>type</td><td>Tipo de la entrega: flex, express o regular</td></tr><tr><td>vehicleCapacity</td><td>Capacidad del vehiculo 1-5 bicicleta-camion</td></tr><tr><td>vehicleId</td><td>Identificador del vehiculo</td></tr><tr><td>price</td><td>Precio de la entrega</td></tr><tr><td>insurance</td><td>Seguro de la entrega</td></tr><tr><td>scheduledStartPickingDate</td><td>Fecha estimada de inicio de recolección</td></tr><tr><td>scheduledEndPickingDate</td><td>Fecha  estimada de final de recolección</td></tr><tr><td>effectivePickupDate</td><td>Fecha real de recolección</td></tr><tr><td>arrivalPickupDate</td><td>Fecha cuando el conductor llega al punto de recolección</td></tr><tr><td>scheduledStartDeliveryDate</td><td>Fecha estimada de inicio de etrega</td></tr><tr><td>scheduledEndDeliveryDate</td><td>Fecha  estimada de final de entrega</td></tr><tr><td>effectiveDeliveryDate</td><td>Fecha real de entrega</td></tr><tr><td>arrivalDeliveryDate</td><td>Fecha cuando el conductor llega al punto de entrega</td></tr><tr><td>creationDate</td><td>Fecha de creación de la entrega</td></tr><tr><td>pickupDueDate</td><td>Fecha máxima de recolección</td></tr><tr><td>deliveryDueDate</td><td>Fecha máxima de entrega</td></tr><tr><td>pickingPlace</td><td>Información de recolección</td></tr><tr><td>pickingPlace.lat</td><td>Latitud del punto de recolección</td></tr><tr><td>pickingPlace.lng</td><td>Longitud del punto de recolección</td></tr><tr><td>pickingPlace.originalAddress</td><td>Dirección de recolección enviada por integración</td></tr><tr><td>pickingPlace.address</td><td>Dirección de recolección corregida por google</td></tr><tr><td>droppingPlace</td><td>Información de entrega</td></tr><tr><td>droppingPlace.lat</td><td>Latitud del punto de entrega</td></tr><tr><td>droppingPlace.lng</td><td>Longitud del punto de entrega</td></tr><tr><td>droppingPlace.originalAddress</td><td>Dirección de entrega enviada por integración</td></tr><tr><td>droppingPlace.address</td><td>Dirección de entrega corregida por google</td></tr><tr><td>recipientInfo</td><td>Información de la persona que va a recibir la entrega</td></tr><tr><td>senderInfo</td><td>Información de la persona que va a enviar la entrega</td></tr><tr><td>state</td><td>Código del estado de la entrega</td></tr><tr><td>tags</td><td>Etiquetas digitales de la entrega</td></tr><tr><td>items</td><td>Información de los paquetes de la entrega</td></tr><tr><td>items.id</td><td>Identificador del paquete</td></tr><tr><td>items.name</td><td>Nombre del paquete</td></tr><tr><td>items.size</td><td>Tamaño del paquete</td></tr><tr><td>items.price</td><td>Precio del paquete</td></tr><tr><td>items.weight</td><td>Peso del paquete</td></tr><tr><td>items.pickedUp</td><td>Indica si ya fue recolectado el paquete</td></tr><tr><td>items.delivered</td><td>Indica si ya fue entregado el paquete</td></tr><tr><td>items.scanned</td><td>Indica si ya fue escaneado el paquete</td></tr><tr><td>items.qty</td><td>cantidad del paquete</td></tr><tr><td>referenceId</td><td>Identificador externo de la entrega.</td></tr><tr><td>notes</td><td>String con la razón del cambio de estado</td></tr><tr><td>attempts</td><td>Número de intentos de entrega</td></tr><tr><td>countryCode</td><td>Código del país</td></tr><tr><td>countryName</td><td>Nombre del país</td></tr><tr><td>currencyCode</td><td>Simbolo de la moneda en el país</td></tr><tr><td>formulaId</td><td>Identificador de la cuota aplicada</td></tr><tr><td>distance</td><td>Distancia entre el punto de recolección y el punto de entrega.</td></tr><tr><td>distanceRoute</td><td>Distancia entre el punto de entrega y el punta anterior en la ruta.</td></tr><tr><td>distanceCharged</td><td>Distancia cobrada</td></tr><tr><td>totalPackagePrice</td><td>Suma de los precios de los paquetes</td></tr><tr><td>eventEntity</td><td>Entidad bajo la cual se generó el evento</td></tr><tr><td>eventDate</td><td>Fecha en que se ejecutó el evento</td></tr><tr><td>lastEventParams</td><td>Información del author del evento </td></tr><tr><td>colleted</td><td>Indica si ya fue recolectado los paquetes</td></tr><tr><td>paid</td><td>Indica si ya fue pagada la entrega</td></tr><tr><td>notesJson</td><td>Objeto donde se guarda el motivo de cambio de estado.</td></tr><tr><td>notesJson.comment</td><td>Comentario general del cambio de estado</td></tr><tr><td>notesJson.reason</td><td>Razón del cambio de estado</td></tr><tr><td>notesJson.reasonId</td><td>Identificador de la razón</td></tr><tr><td>itemsNumber</td><td>Cantidad total de items en la entrega</td></tr><tr><td>itemsWeight</td><td>Peso total de la entrega</td></tr><tr><td>itemsPrice</td><td>Precio total de la de la entrega</td></tr><tr><td>references</td><td>Información adicional de la entrega</td></tr><tr><td>incidences</td><td>Incidencias de la entrega</td></tr><tr><td>metadata</td><td>Información adicional de la entrega</td></tr><tr><td>previousStatus</td><td>Estado anterior al actual</td></tr><tr><td>eventType</td><td>Tipo de evento</td></tr><tr><td>eventAuthor</td><td>Información del usuario que realizó el evento</td></tr><tr><td>eventCreatedAt</td><td>Fecha en que se creó el evento</td></tr><tr><td>eventDescription</td><td>Descripción del evento</td></tr><tr><td>eventParams</td><td>Parametros enviados al evento</td></tr><tr><td>status</td><td>Estado actual de la tarea</td></tr><tr><td>eventId</td><td>Identificador del evento</td></tr><tr><td>images</td><td>Arreglo de imágenes de las pruebas de entrega. Puede ser en url o en base64 según la configuración</td></tr><tr><td>signature</td><td>Adjunta la firma del destinatario como una imagen png con fondo transparente.Puede ser en url o en base64 según la configuración</td></tr><tr><td>trackingUrl</td><td>URL de seguimiento privada de la entrega.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### ¿Cómo probar el webhook?

Una vez ya creada la automatización se puede proceder a probarla.&#x20;

Si aun no tiene un endpoint listo para recibir las actualizaciones, puede usar [uno de prueba](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63) para testear la configuración del webhook y ver el payload.

Para este ejemplo configuraremos la automatización de webhook para que envíe la actualización cuando la entrega cambie a estado "Completado".

<figure><img src="/files/2dq6A0w4hQk2OjSPM7Q2" alt=""><figcaption><p>Webhook</p></figcaption></figure>

1. Crear una entrega [por dash](https://dash.shippify.co/deliver) ( si ya la tiene creada puede saltar este paso ).&#x20;
2. Cambiar el estado según corresponda la automatización, en este caso, cambiaremos al estado Completado porque así configuramos nuestra automatización de pruebas.

<figure><img src="/files/soU4fPdXym2hF2liB6g8" alt=""><figcaption><p>Actualización de estado</p></figcaption></figure>

3. Observar el payload enviado al webhook, en este caso utilizamor un [webhook de pruebas](https://webhook.site/#!/view/4ffe8bb1-eb10-4560-812a-fc7d0ee54c63/aa83de64-adbe-4923-ba2a-e404399a50bc/1) asi que podremos ver el payload enviado, en el caso que ya tenga un endpoint configurado para recibir las notificaciones puede colocar un log para identificar que se realizó la llamada.

<figure><img src="/files/1Qbh93mxwHuSarKDI1PF" alt=""><figcaption></figcaption></figure>

Dentro de la automatización, se puede observar las ejecuciones fallidas y exitosas de la automatización junto al identificador de la entrega asociada, en este caso tenemos una ejecución exitosa para la entrega `t-pruaas-5104.`

<figure><img src="/files/OqKGvqSY4uwHTwy3h993" alt=""><figcaption><p>Histograma</p></figcaption></figure>

## Suscriptores a errores

Cuando este configurado exitosamente el webhook se puede activar las subscripciones a errores, aqui podrá registrar uno o varios correos en donde les llegarán alertas cada que una notificación falle el envío o el endpoint responda con un error.

<figure><img src="/files/osTFL1l0zPoeB1ovbld1" alt=""><figcaption><p>Suscriptores a errores</p></figcaption></figure>

<figure><img src="/files/7hrUtcOT0QUa10iPy6w6" alt=""><figcaption><p>Email de notificación de error</p></figcaption></figure>

## Configuración personalizada

Si requiere utilizar el webhook pero necesita recibir un payload diferente al anterior, se deberá solicitar por correo adjuntando el payload que desea recibir por cada estado y [la tabla con los estados equivalentes en shippify](/developers/guia-de-integracion/procesos-basicos/actualizacion-de-estados/estados.md#enlace-de-estados-con-plataforma-externa).&#x20;

<details>

<summary>Ejemplo de request</summary>

{% code overflow="wrap" %}

```
Buenas días,

Deseo actualizar los pedidos en mi plataforma por medio de un webhook con payload personalizado.

* Email de mi compañia en shippify: example@shippify.co
* Tabla con los estados equivalentes en shippify y los payloads personalizados: Documento adjunto

De antemano gracias,

Att.
Nombre example
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.shippify.co/developers/guia-de-integracion/procesos-basicos/actualizacion-de-estados/suscripciones-a-webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.