Invocar un webhook desde un disparador

Actualizado

Nota: Este artículo es técnico, por lo que recomendamos contar con alguien que tenga la experiencia técnica adecuada. Si tiene alguna pregunta, contacte con nosotros en support@azumuta.com.

Un webhook trigger notifica a otro sistema en cuanto ocurre algo en Azumuta, por ejemplo cuando se completa una orden de producto o se informa de un problema. Úselo en lugar de sondear la REST API. Azumuta envía solo los datos de ese evento, en el momento en que sucede. Para el patrón ERP más amplio, consulte ERP Integration.

Este artículo explica cómo configurar un desencadenador Call a webhook: dónde configurarlo, qué atributos rellenar, qué envía Azumuta a su endpoint, qué ocurre cuando la llamada falla y cómo comprobar y reintentar ejecuciones.

Añadir un webhook trigger

  1. Haga clic en Settings bajo Management.
  2. Haga clic en Triggers bajo Integrations.
  3. Haga clic en Add trigger (el botón amarillo con el signo más).
  4. Rellene los campos descritos más abajo.
  5. Cuando termine, haga clic en Add.

Scope, What and When

Seleccione estos primero:

  • Scope: A qué se aplica el trigger, por ejemplo a todas las órdenes de producto, una categoría de artículos, instrucciones de trabajo de auditoría seleccionadas o un tablero de mejora.
  • What: Seleccione Call a webhook.
  • When: El evento que activa el webhook, por ejemplo When a product order is finished o When an audit is finished.

Los eventos por scope se enumeran en estos artículos:

Tras la creación, puede edit or delete el trigger y revisar el usage history.

Attributes

Tras seleccionar What y When, la sección Attributes muestra las opciones del webhook:

  • Endpoint: La URL HTTPS que Azumuta llamará (el placeholder empieza por https://). Este endpoint debe ser accesible desde los servidores de Azumuta.
  • Method: GET, POST, PUT o PATCH. El valor por defecto es GET.
  • Payload: Visible para todos los métodos excepto GET. Introduzca aquí el contenido personalizado del cuerpo. Puede usar parámetros en este campo.
  • Authentication: Cómo se identifica Azumuta ante su endpoint. Véase Authentication.
  • Request timeout: Cuántos segundos espera Azumuta por una respuesta antes de considerar el intento como fallido. Introduzca un valor de 1 a 300. Déjelo vacío para usar el valor por defecto de 30 segundos.
  • Retry automatically when the webhook fails: Active esta opción para reintentar una llamada fallida. Véase Retry failed calls.

Authentication

Seleccione cómo se identifica Azumuta ante su endpoint. Los nuevos triggers empiezan en None.

  • None: Azumuta no envía credenciales.
  • Header: Azumuta envía un encabezado con cada llamada. Escriba el Header name (por ejemplo X-API-Key), y después elija el valor: Custom value (un secreto que escribe) o API key from device (la clave de un Api Device). Los nombres de encabezado User-Agent, Origin y Content-Type están reservados.
  • Basic: Azumuta envía un nombre de usuario y contraseña usando autenticación HTTP Basic.
  • OAuth client credentials: Azumuta solicita primero un token de acceso y lo envía con la llamada. Rellene el Token URL (debe ser una dirección HTTPS), Client ID, Client secret y, si su proveedor lo requiere, Scope.

Un secreto que introduzca (un valor personalizado de encabezado, una contraseña o un client secret) se guarda de forma segura. Después el campo solo muestra ******, nunca el valor guardado. Cambiar la URL del webhook borra el secreto guardado, y para OAuth también lo hace cambiar el token URL, por lo que tendrá que introducirlo de nuevo.

What Azumuta sends

Azumuta envía campos específicos del evento con cada llamada:

Scope Typical fields
Product orders identifier (número de orden de producto), y cuando proceda workinstructionId y recordingId
Issues issueId, issueNumber (y para algunos eventos, campos relacionados con columna/acción)
Audits recordingId, workinstructionId, y campos de auditoría relacionados como auditNumber

Cómo se entregan esos campos depende del método:

  • GET: Los campos se añaden como parámetros de consulta URL.
  • POST, PUT and PATCH: Los campos se envían como JSON en el cuerpo de la petición. Si ha configurado un Payload personalizado, ese contenido aparece anidado bajo la clave payload en el cuerpo JSON, junto a los campos del evento indicados arriba.

Cada llamada también lleva estas cabeceras, para que su sistema pueda reconocer la llamada y detectar repeticiones:

Header Value
X-Azumuta-Trigger-Run-Id El ID de la ejecución del trigger. Permanece igual en todos los intentos de la misma ejecución.
X-Azumuta-Trigger-Id El ID del trigger.
X-Azumuta-Webhook-Attempt El número de intento. La primera llamada es 1, el primer reintento es 2, y así sucesivamente.

Retry failed calls

Una llamada se considera fallida cuando su endpoint responde con un estado de error (cualquier estado distinto de 2xx), no responde dentro del Request timeout, o no se puede alcanzar. Una llamada fallida se registra como una ejecución fallida, por lo que una integración que falla aparece como tal en el historial de ejecuciones.

Sin reintentos, una llamada fallida no se repite. Una breve interrupción en su endpoint implicaría perder la llamada. Active Retry automatically when the webhook fails para repetirla:

  • Retries: Número de intentos extra tras el primero, de 1 a 10. Con 3 reintentos, Azumuta realiza hasta 4 llamadas. El valor por defecto es 3.
  • Wait between retries: El tiempo entre intentos: 15 minutos, 30 minutos, 1 hora, 2 horas, 4 horas, 8 horas o 24 horas. El valor por defecto es 1 hora.
  • Only retry during set hours: Márquelo para limitar los reintentos a una ventana horaria, por ejemplo cuando su sistema está desconectado por la noche. Establezca la hora de inicio y fin en Between y and, y seleccione la Timezone. Un reintento que caiga fuera de la ventana esperará hasta que la ventana se abra de nuevo. La ventana empieza a las 06:00 y termina a las 22:00 por defecto.

Datos importantes:

  • Cada reintento envía los mismos datos del evento que la primera llamada. El reintento usa el trigger tal como esté configurado en ese momento, por lo que un nuevo endpoint o nuevas credenciales se aplican a reintentos que aún estén pendientes.
  • La ejecución se registra como Success tan pronto como un intento tiene éxito, y como Failed una vez que el último reintento ha fallado.
  • Si reduce el número de reintentos mientras una ejecución está en espera, la ejecución se detiene en el nuevo límite. Si desactiva los reintentos o elimina el trigger, la ejecución en espera se registra como fallida en lugar de reintentarse.
  • La primera llamada se realiza en el momento en que ocurre el evento. La ventana solo se aplica a los reintentos.

Como un reintento puede llegar después de una llamada que sí alcanzó su sistema (por ejemplo, cuando su sistema la procesó pero la respuesta se perdió), diseñe su endpoint para que recibir el mismo evento dos veces no cause problemas. Use la cabecera X-Azumuta-Trigger-Run-Id para reconocer una repetición.

Comprobar y reintentar ejecuciones

Abra el historial de uso del trigger para ver cada ejecución. Véase See the list of triggers in your workspace and each trigger’s usage history.

Cada ejecución tiene uno de estos estados:

Status Meaning
Running Azumuta está realizando la llamada.
Waiting for retry El último intento falló y hay programado un reintento. La ejecución muestra qué intento es el siguiente (por ejemplo "Attempt 2 of 4") y cuándo, junto con la razón por la que falló el último intento.
Success El endpoint respondió con un estado 2xx.
Failed La llamada falló y no quedan reintentos, o los reintentos están desactivados.

Una ejecución con más de un intento también muestra cuántos intentos realizó.

Para ejecutar el siguiente intento de inmediato en lugar de esperar el intervalo, haga clic en Retry now junto a una ejecución que esté Waiting for retry.

Use the REST API to check and retry runs

Una integración puede leer el historial de ejecuciones y forzar una ejecución en espera a pasar mediante sí misma con la Azumuta REST API. Los endpoints están en la sección Triggers de la documentación de la API dentro de la aplicación.

Endpoint What it does
GET /api/v1/triggers/runs Lista ejecuciones de triggers, de más recientes a más antiguas.
GET /api/v1/triggers/runs/{triggerRunId} Devuelve una ejecución completa, incluyendo cada intento con la petición enviada y la respuesta recibida.
POST /api/v1/triggers/runs/{triggerRunId}/retry Ejecuta inmediatamente el siguiente intento de una ejecución en espera.

List runs. Filtre la lista con estos parámetros de consulta:

  • triggerId: solo ejecuciones de estos triggers.
  • status: solo ejecuciones en estos estados: running, retrying (la ejecución falló y está esperando su siguiente intento), success o failed.
  • scope: solo ejecuciones de triggers en estos scopes.
  • productId y issueId: solo ejecuciones para estas órdenes de producto o issues.
  • startedAfter y startedBefore: solo ejecuciones iniciadas dentro de este intervalo, como timestamps Unix en milisegundos.
  • limit (hasta 100, por defecto 100) y skip: paginar los resultados.

Cada ejecución en la lista tiene un id, triggerId, scope, type, event, status, startTime, endTime, errorMessage y, para webhooks, el endpoint y nextAttemptAt (cuándo está planificado el siguiente intento). Para encontrar las llamadas que no llegaron en un periodo, filtre por status=failed y el periodo.

Retrieve a run. La ejecución completa añade attempts: para cada llamada su número, hora de inicio y fin, la request (método, URL y body), la response (estado y body) y, cuando la llamada no pudo realizarse en absoluto, el mensaje de error. Las credenciales en la URL aparecen redactadas.

Retry a run. La ejecución debe estar en retrying, de lo contrario la llamada se rechaza. La respuesta es la ejecución tal como queda después del intento: success o failed si el intento la resolvió, o retrying de nuevo si falló y se programó otro intento. Un reintento programado que se dispare en el mismo momento no envía la petición dos veces.

Access. Autentíquese como se describe en Azumuta’s REST API. Si el experimento de scopes de la API está habilitado para su workspace, la clave necesita el scope triggers:read para listar ejecuciones y leerlas en detalle, y el scope triggers:write para reintentar una ejecución. Leer una ejecución completa y reintentar una ejecución también requieren el derecho Manage triggers, o el derecho de gestionar triggers del scope de la ejecución, para el usuario tras la llamada.

En esta página