Webhook de disparo de rutinas

Inicia una rutina desde tus propios sistemas. La dirección, los cinco modos de firma, las cabeceras, la carga, las respuestas, los reintentos y la protección contra repeticiones, con código de firma en curl, JavaScript y Python.

Veyra Docs TeamActualizado el 3 min de lecturaVersión 3 · Historial

Un disparador de webhook permite que cualquier sistema inicie una rutina: una alerta de monitorización, un pipeline de CI, un formulario, otro producto. Cada entrega crea una ejecución; el JSON que envías se guarda en la ejecución y se muestra al agente como datos.

HTTP
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fire

Configúralo

  1. Abre la rutina y luego Triggers › Add trigger › Webhook.
  2. Elige un modo de firma (abajo). Empieza con el disparador en modo de prueba (setupPending: true en la API) mientras configuras el emisor.
  3. Copia la URL y el secreto. El secreto se muestra una sola vez; Rotate secret genera uno nuevo y el anterior deja de funcionar de inmediato.
  4. Envía una entrega de prueba. En modo de prueba se comprueba y se registra, pero no inicia ninguna ejecución, así que puedes confirmar la autenticación sin riesgo.
  5. Desactiva el modo de prueba. A partir de ahí, cada entrega aceptada inicia una ejecución.

Modos de firma

Modo Envía Elígelo cuando
bearer (por defecto) Authorization: Bearer <secret> Tu emisor puede añadir una cabecera.
hmac_sha256 X-Veyra-Timestamp y X-Veyra-Signature Quieres solicitudes firmadas, con límite de tiempo y que no se puedan repetir.
github_hmac X-Hub-Signature-256: sha256=<hex> El emisor firma como GitHub o Sentry (HMAC del cuerpo sin procesar).
app_webhook Bearer o X-Hub-Signature-256 Una app conectada entrega eventos; la carga se pasa al agente.
none Nada Solo pueden elegirlo personas; la URL por sí sola es el secreto. Los agentes no pueden crear disparadores sin autenticación.

hmac_sha256

Calcula la firma sobre la marca de tiempo, un punto y los bytes exactos del cuerpo:

Text
signature = hex( HMAC-SHA256( secret, timestamp + "." + raw_body ) )

Envía X-Veyra-Timestamp: <timestamp> (segundos o milisegundos Unix) y X-Veyra-Signature: sha256=<signature>. Una marca de tiempo fuera de la ventana contra repeticiones del disparador (300 segundos, salvo que elijas entre 30 y 86 400) se rechaza, y la misma solicitud firmada solo se acepta una vez.

Cabeceras

Cabecera Obligatoria Significado
Content-Type: application/json Sí El cuerpo debe ser un objeto JSON.
Authorization bearer, app_webhook Bearer <secret>.
X-Veyra-Timestamp hmac_sha256 La hora Unix de la firma.
X-Veyra-Signature hmac_sha256 sha256= y el HMAC en hexadecimal. También se acepta en github_hmac.
X-Hub-Signature-256 github_hmac sha256= y el HMAC hexadecimal del cuerpo sin procesar.
Idempotency-Key Recomendada Tu ID para este evento. Una repetición devuelve el primer resultado. Si está presente, se usa X-GitHub-Delivery.
X-Veyra-Idempotency-Scope No trigger (por defecto): las claves son únicas por disparador. routine: únicas entre todos los disparadores de la rutina.

Cuerpo

Cualquier objeto JSON de hasta 10 MB. Dos campos tienen un significado propio:

  • variables: un objeto con valores para las variables de la rutina, por ejemplo {"variables": {"ticket": "SUP-812"}}.
  • Todo lo demás se guarda en la ejecución como su carga.

Envía una solicitud firmada

curl
URL="https://intelligence-api.veyra.so/api/routine-triggers/public/$PUBLIC_ID/fire"
BODY='{"variables":{"ticket":"SUP-812"},"severity":"high"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" -hex | sed 's/^.* //')

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Veyra-Timestamp: $TS" \
  -H "X-Veyra-Signature: sha256=$SIG" \
  -H "Idempotency-Key: SUP-812" \
  --data-binary "$BODY"
JavaScript
import { createHmac } from "node:crypto";

const body = JSON.stringify({ variables: { ticket: "SUP-812" }, severity: "high" });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac("sha256", process.env.VEYRA_TRIGGER_SECRET)
  .update(`${timestamp}.`)
  .update(body)
  .digest("hex");

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Veyra-Timestamp": timestamp,
    "X-Veyra-Signature": `sha256=${signature}`,
    "Idempotency-Key": "SUP-812",
  },
  body, // envía exactamente los bytes que firmaste
});
console.log(response.status, await response.json());
Python
import hashlib, hmac, json, os, time
import requests

secret = os.environ["VEYRA_TRIGGER_SECRET"].encode()
body = json.dumps({"variables": {"ticket": "SUP-812"}, "severity": "high"}, separators=(",", ":")).encode()
timestamp = str(int(time.time()))
signature = hmac.new(secret, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()

response = requests.post(
    url,
    data=body,  # envía exactamente los bytes que firmaste
    headers={
        "Content-Type": "application/json",
        "X-Veyra-Timestamp": timestamp,
        "X-Veyra-Signature": f"sha256={signature}",
        "Idempotency-Key": "SUP-812",
    },
    timeout=15,
)
print(response.status_code, response.json())

Con bearer, envía solo Authorization: Bearer $TRIGGER_SECRET y el JSON.

Respuestas

Estado Cuerpo Significado
202 La ejecución de la rutina Aceptada. El status de la ejecución indica qué pasó (por ejemplo, se creó una tarea o la entrega se unió a una ejecución activa).
202 {"status": "test_received", "test": true} Modo de prueba: autenticada y registrada, sin iniciar ninguna ejecución.
202 {"status": "ignored"} Una app conectada envió un evento al que el disparador no está suscrito.
400 {"error": ...} El cuerpo no es un objeto JSON o una cabecera tiene un valor incorrecto.
401 {"error": ...} Falta el secreto o la firma, o son incorrectos, o la marca de tiempo está fuera de la ventana.
404 {"error": ...} No existe ese disparador.
409 {"error": ...} La rutina está archivada, o el disparador o la rutina no están activos.
415 {"error": ...} Content-Type no es application/json.

Las entregas rechazadas quedan registradas en el disparador (last delivery: rejected) y en el registro de actividad, para que veas los intentos fallidos sin exponer lo que se envió.

Reintentos y duplicados

  • Reintenta ante un error de red, un tiempo de espera agotado, un 429 o un 5xx, con la misma Idempotency-Key. Una clave repetida devuelve el primer resultado en lugar de una segunda ejecución.
  • Con hmac_sha256, vuelve a firmar cada reintento con una marca de tiempo nueva; la protección contra repeticiones va por firma.
  • No reintentes respuestas 4xx distintas de 429; corrige la solicitud.

Qué ve el agente

La tarea de la ejecución contiene la petición de la rutina. La carga que enviaste se adjunta como datos, marcada como procedente del exterior y como algo que no debe seguirse como instrucciones. Da a la rutina instrucciones claras sobre cómo tratar la carga.

Consulta Fire a public routine trigger, Create a routine trigger y Rotate a routine trigger secret en la referencia de la API.

EntrantesRutinasWebhooks