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.

Webhook

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 para elaborarla. Por cada estado que necesites actualizar en tu plataforma vas a tener que crear un webhook diferente siguiendo los pasos dados:

Crear un Webhook

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 y pulsa el botón CREAR AUTOMATIZACIÓN +.

Automatización

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.

Configuración

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.

Configuración

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

Parámetro	Descripción	Obligatorio
Webhook	URL a la que se enviará el payload del evento.
Método HTTP	Método de solicitud HTTP para enviar el payload.
Prueba de entrega	En caso de que el evento tenga imágenes adjuntas, elige si deseas añadirlas en tu payload como images(Array[]).
HTTP Headers	Headers personalizados para la solicitud HTTP.
Firma del destinatario	Adjunta la firma del destinatario como imagen png con fondo transparente. Lo añade al payload como signature (String)
Formato Base64	Las imágenes de la prueba de entrega o firma se envían en formato base64. (Si no se marca, entonces es una url)
URL de seguimiento	Incluye URL privada de seguimiento de la entrega. Lo encontrarás en el payload como trackingUrl (String)

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.

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": ["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": 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}"

}

DETALLE

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

¿Cómo probar el webhook?

Una vez ya creada la automatización se puede proceder a probarla.

Si aun no tiene un endpoint listo para recibir las actualizaciones, puede usar uno de prueba 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".

Webhook

1. Crear una entrega por dash ( si ya la tiene creada puede saltar este paso ).

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.

Actualización de estado

1. Observar el payload enviado al webhook, en este caso utilizamor un webhook de pruebas 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.

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.

Histograma

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.

Suscriptores a errores

Email de notificación de error

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.

Ejemplo de request

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: [e-mail]
* Tabla con los estados equivalentes en shippify y los payloads personalizados: Documento adjunto

De antemano gracias,

Att.
Iliana Bolaños