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.
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.
POST https://intelligence-api.veyra.so/api/routine-triggers/public/{publicId}/fireConfigúralo
- Abre la rutina y luego Triggers › Add trigger › Webhook.
- Elige un modo de firma (abajo). Empieza con el disparador en modo de prueba (
setupPending: trueen la API) mientras configuras el emisor. - 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.
- 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.
- 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:
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
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"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());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
429o un5xx, con la mismaIdempotency-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
4xxdistintas de429; 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.