Español

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.

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:

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

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.

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.

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

ParámetroDescripciónObligatorio

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.

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

}

¿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".

  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.

  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.

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.

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: iliana@shippify.co
* Tabla con los estados equivalentes en shippify y los payloads personalizados: Documento adjunto

De antemano gracias,

Att.
Iliana Bolaños

AnteriorActualización de estadosSiguientePolling Continuo

Última actualización