Webhook de déclenchement de routine

Lancez une routine depuis vos propres systèmes. L'adresse, les cinq modes de signature, les en-têtes, la charge utile, les réponses, les relances et la protection anti-rejeu, avec du code de signature en curl, JavaScript et Python.

Veyra Docs TeamMis à jour le 3 min de lectureVersion 3 · Historique

Un déclencheur webhook permet à n'importe quel système de lancer une routine : une alerte de supervision, un pipeline de CI, un formulaire, un autre produit. Chaque livraison crée une exécution ; le JSON envoyé est stocké sur l'exécution et présenté à l'agent comme des données.

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

Mise en place

  1. Ouvrez la routine, puis Triggers › Add trigger › Webhook.
  2. Choisissez un mode de signature (ci-dessous). Démarrez le déclencheur en mode test (setupPending: true dans l'API) pendant que vous configurez l'émetteur.
  3. Copiez l'URL et le secret. Le secret n'est affiché qu'une fois ; Rotate secret en génère un nouveau et l'ancien cesse aussitôt de fonctionner.
  4. Envoyez une livraison de test. En mode test, elle est vérifiée et enregistrée mais ne lance aucune exécution : vous pouvez confirmer l'authentification sans risque.
  5. Désactivez le mode test. Désormais, chaque livraison acceptée lance une exécution.

Modes de signature

Mode Envoyer Le choisir quand
bearer (par défaut) Authorization: Bearer <secret> Votre émetteur peut définir un en-tête.
hmac_sha256 X-Veyra-Timestamp et X-Veyra-Signature Vous voulez des requêtes signées, limitées dans le temps et impossibles à rejouer.
github_hmac X-Hub-Signature-256: sha256=<hex> L'émetteur signe comme GitHub ou Sentry (HMAC du corps brut).
app_webhook Bearer, ou X-Hub-Signature-256 Une application connectée livre des événements ; la charge utile est transmise à l'agent.
none Rien Seules des personnes peuvent le choisir ; l'URL seule fait office de secret. Les agents ne peuvent pas créer de déclencheurs non authentifiés.

hmac_sha256

Calculez la signature sur l'horodatage, un point, puis les octets exacts du corps :

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

Envoyez X-Veyra-Timestamp: <timestamp> (secondes ou millisecondes Unix) et X-Veyra-Signature: sha256=<signature>. Un horodatage hors de la fenêtre anti-rejeu du déclencheur (300 secondes, sauf si vous choisissez entre 30 et 86 400) est refusé, et une même requête signée n'est acceptée qu'une fois.

En-têtes

En-tête Obligatoire Signification
Content-Type: application/json Oui Le corps doit être un objet JSON.
Authorization bearer, app_webhook Bearer <secret>.
X-Veyra-Timestamp hmac_sha256 L'heure Unix de la signature.
X-Veyra-Signature hmac_sha256 sha256= suivi du HMAC en hexadécimal. Accepté aussi pour github_hmac.
X-Hub-Signature-256 github_hmac sha256= suivi du HMAC hexadécimal du corps brut.
Idempotency-Key Recommandé Votre identifiant pour cet événement. Une répétition renvoie le premier résultat. X-GitHub-Delivery est utilisé s'il est présent.
X-Veyra-Idempotency-Scope Non trigger (par défaut) : les clés sont uniques par déclencheur. routine : uniques sur tous les déclencheurs de la routine.

Corps

N'importe quel objet JSON, jusqu'à 10 Mo. Deux champs ont un sens particulier :

  • variables : un objet de valeurs pour les variables de la routine, par exemple {"variables": {"ticket": "SUP-812"}}.
  • Tout le reste est stocké sur l'exécution comme charge utile.

Envoyer une requête signée

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, // envoyez exactement les octets signés
});
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,  # envoyez exactement les octets signés
    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())

Avec bearer, envoyez seulement Authorization: Bearer $TRIGGER_SECRET et le JSON.

Réponses

Statut Corps Signification
202 L'exécution de la routine Acceptée. Le status de l'exécution indique ce qui s'est passé (par exemple une tâche a été créée, ou la livraison a été fusionnée avec une exécution en cours).
202 {"status": "test_received", "test": true} Mode test : authentifiée et enregistrée, aucune exécution lancée.
202 {"status": "ignored"} Une application connectée a envoyé un événement auquel le déclencheur n'est pas abonné.
400 {"error": ...} Le corps n'est pas un objet JSON, ou un en-tête a une valeur incorrecte.
401 {"error": ...} Secret ou signature absent ou incorrect, ou horodatage hors de la fenêtre.
404 {"error": ...} Ce déclencheur n'existe pas.
409 {"error": ...} La routine est archivée, ou le déclencheur ou la routine n'est pas actif.
415 {"error": ...} Content-Type n'est pas application/json.

Les livraisons rejetées sont enregistrées sur le déclencheur (last delivery: rejected) et dans le journal d'activité : vous voyez les tentatives échouées sans exposer ce qui a été envoyé.

Relances et doublons

  • Relancez après une erreur réseau, un délai dépassé, un 429 ou un 5xx, avec la même Idempotency-Key. Une clé répétée renvoie le premier résultat au lieu d'une seconde exécution.
  • Avec hmac_sha256, signez de nouveau chaque relance avec un horodatage neuf ; l'anti-rejeu s'applique par signature.
  • Ne relancez pas les réponses 4xx autres que 429 ; corrigez plutôt la requête.

Ce que voit l'agent

La tâche de l'exécution contient la demande de la routine. La charge utile envoyée y est jointe comme données, marquée comme venant de l'extérieur et à ne pas suivre comme des instructions. Donnez à la routine des instructions claires sur la façon de traiter la charge utile.

Voir Fire a public routine trigger, Create a routine trigger et Rotate a routine trigger secret dans la référence de l'API.

EntrantsRoutinesWebhooks