Saltar al contenido principal

Webhooks

Un webhook consiste en una URL por medio de la cual el servidor*, Cargamos en este caso, puede iniciar la comunicación con el cliente, y suministrar información en la medida que esta se haga disponible y sin requerir que el cliente la solicite bajo demanda. Nótese que las comunicaciones habitualmente son iniciadas por el cliente. En este caso, es el servidor el que inicia la misma.

  • Cliente/Servidor en el contexto de esta descripción alude a la pareja Shipper/Cargamos respectivamente

El sistema de webhooks permite al shipper recibir notificaciones en “tiempo real” de los cambios de estado de cada uno de los shipments que fueron integrados. Dichas notificaciones se reciben de forma independiente, es decir, así se hayan integrado múltiples órdenes (en batch), las notificaciones se reciben de forma individual, para cada shipmentId/trackingId activo. Solo es posible registrar un solo webhook por shipper.

En resumen, el sistema de webhooks permite:

  1. Registrar un webhook (URL), perteneciente al shipper en la cual se notificarán los cambios de estados de los shipments.
  2. Elegir los estados que resultan de interés para el shipper. Ejemplo: es posible que al shipper solo le interese ser notificado de los estados de DELIVERED y MISHAP. El primero para saber que el paquete fue entregado exitosamente, y el segundo para ser consciente que hubo un problema con el paquete y se están esperando instrucciones
  3. Suspender el envío de notificaciones vía webhook.

Para gestionar el servicio de webhooks, se provee la API de webhooks que puede ser consultada en la referencia de la API.

Un ejemplo de un flujo de uso habitual se observa en la figura. En el primer paso, se hace el registro del webhook indicando los estados de interés, DELIVERED y OUT_FOR_DELIVERY. Posteriormente, se recibe una notificación cada vez que alguna de los shipments transición a los estados de interés (i.e. DELIVERED y OUT_FOR_DELIVERY).

Dropoff

Fig. Uso habitual del sistema de webhooks

Un ejemplo del body integrado via webhook:

{
  "state": "DELIVERY_ATTEMPTED",
  "label_id": "CH00000000044",
  "anomalies": {
    "anomaly_type": "RECIPIENT_NOT_AT_ADDRESS",
    "description": null
  },
  "evidences": [
    {
      "type": "IMAGE",
      "name": "FACADE",
      "value": null,
      "url": "https://storage.googleapis.com/valhalla-shippers-dev.appspot.com/evidences/S6SNXFMSAZ001YSS13CJ%3A1686102862000%3AIMAGE%3A0.jpeg?Expires=1686106463&GoogleAccessId=kubernetes-services%40valhalla-shippers-dev.iam.gserviceaccount.com&Signature=LvsL%2FI62lpcfxLsfgpZyCTAeEg%2Bdo7k4NnSleKyT63lT25z01XuYJ5Q89WgF3b9jp3tmKO2%2F%2F4F02vDhO7bAkaiOh%2FbzMYKcqHpHQX0u0QLVejDWSyMBfG1UCpXPm%2FanP6fidJzYRQf9bIDde8ul8ef36SOiXct4EsJojZM%2FGcIgHo7cYcrnS87c4%2BmP8XjEvSCgosbZ%2F6%2F%2B%2BxF1STy8YNKJ%2BqeS157FR96c6GLsLPNE%2BE6Llr3REomxl4myO6hWmzeU%2FRjwbMbKdZIo8ALeg%2Bu%2Fe1gaHmelpBo3h1BI1bbmVXzmtGHGwgeodtnXRMWWV3QZ7w8pDw3Utqy8cPWGjw%3D%3D",
      "url_expiration_timestamp": 1686106463714
    }
  ],
  "tracking_id": "S6SNXFMSAZ001YSS13CJ",
  "shipper_tracking_id": "CH00000000044",
  "timestamp": 1686102861482,
  "lat": 19.5044985,
  "lng": -99.229485
}

Nótese en este ejemplo que se suministran los valores de trackingId y de shipperTrackingId. Existen webhhooks (i.e. MISHAP) que proporcionan información adicional en texto en el campo anomalies. Aquí se suele indicar, para el ejemplo de MISHAP, si el paquete fue golpeado, robado, etc. Otro ejemplo en el que se hace uso del campo context es cuando una entrega no fue exitosa, caso en el cual se indican las razones por la cual no fue posible realizarse.

Todos los eventos que se ocasionan durante la entrega están geo-taggeados (tienen un valor no nulo para lat y lng). Finalmente, el campo timestamp refleja el instante de tiempo en el que se registra el evento, mas no el tiempo de integración o persistencia del mismo. Este valor se expresa siempre como un Unix timestamp en milisegundos.

Info

Los webhooks son llamados POST que se realizan a la URL suministrada en targetAddress, con el cuerpo sugerido en el ejemplo. Por lo tanto es necesario que la respuesta tenga un status 2XX, o de lo contrario el sistema de webhooks reintentará la notificación.

Nota:

Los urls a imágenes de evidencias son temporales, el campo url_expiration_timestamp indica hasta qué fecha pueden ser accedidos. Si se requiere ver la evidencia pasada esa fecha, es necesario llamar al endpoint /v1/shipments-tracking/{label}