API Prompt

Le déclencheur API Prompt expose un point de terminaison HTTP qui accepte une instruction en langage naturel (ainsi qu'un contexte structuré et des métadonnées optionnels) et exécute un workflow en rendant ces champs disponibles en tant que sorties de bloc. C'est le bon déclencheur quand vous souhaitez que votre API ressemble à « discuter avec un workflow » plutôt qu'à « remplir ce schéma JSON ».

Contrat de requête

POST /api/webhooks/prompt/{path}
Content-Type: application/json

{
  "prompt": "Summarize these PDFs and email me the result",
  "context": { "pdf_ids": ["abc", "def"] },
  "metadata": { "request_origin": "internal-app-v2" }
}

• prompt (string, requis) — instruction en langage naturel. Limitée à maxPromptLength (par défaut 10 000 caractères, limite absolue 50 000).
• context (objet, optionnel) — JSON arbitraire. Utilisez-le pour transmettre des références structurées (IDs, chemins de fichiers, profil utilisateur) en complément du prompt.
• metadata (objet, optionnel) — identifiants fournis par l'appelant que vous souhaitez exposer pour le routage/la journalisation.

Tout champ supplémentaire au niveau racine est ignoré. Le JSON imbriqué dans context et metadata est conservé.

Sorties de bloc

Disponibles dans les blocs en aval via <apiprompt1.*> :

Authentification

Prend en charge les 4 mêmes modes que le déclencheur Webhook générique :

Voir Webhooks → Authentification pour des exemples de signature en bash / Node / Python.

Appel depuis un consommateur — démarrage rapide HMAC

Lorsque vous configurez l'authentification HMAC-SHA256, la plateforme attend un condensé hexadécimal des octets bruts exacts de votre corps de requête, signé avec votre secret partagé, envoyé dans l'en-tête X-Signature (ou le nom que vous avez défini sous Signature header).

curl

WEBHOOK_URL="https://staging-app.mybotbox.com/api/webhooks/prompt/<path>"
SECRET="<your HMAC secret>"

BODY='{"prompt":"Summarize last week of standup notes","context":{"team":"platform"}}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')

curl -X POST "$WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  --data-raw "$BODY"

Notes :

• X-Timestamp (secondes Unix ou ISO-8601) est requis lorsque la fenêtre de rejeu du déclencheur est activée (par défaut 300s). Sans lui, vous obtiendrez 401 — timestamp outside replay window.
• Le préfixe sha256= est accepté mais non requis — le serveur le supprime sans tenir compte de la casse.
• X-Idempotency-Key: <votre-id-de-requête> est optionnel mais recommandé, afin que les nouvelles tentatives retournent 200 { "status": "duplicate" } sans relancer le workflow.

Python

import hmac, hashlib, json, time, requests

WEBHOOK_URL = "https://staging-app.mybotbox.com/api/webhooks/prompt/<path>"
SECRET = b"<your HMAC secret>"

body = json.dumps(
    {"prompt": "Summarize last week of standup notes", "context": {"team": "platform"}},
    separators=(",", ":"),
).encode()
sig = hmac.new(SECRET, body, hashlib.sha256).hexdigest()

resp = requests.post(
    WEBHOOK_URL,
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Signature": sig,
        "X-Timestamp": str(int(time.time())),
        "X-Idempotency-Key": "req-2026-05-17-001",
    },
)
print(resp.status_code, resp.text)

Node.js / TypeScript

import { createHmac } from 'node:crypto'

const WEBHOOK_URL = 'https://staging-app.mybotbox.com/api/webhooks/prompt/<path>'
const SECRET = process.env.MBB_HMAC_SECRET! // never hardcode

const body = JSON.stringify({
  prompt: 'Summarize last week of standup notes',
  context: { team: 'platform' },
})
const sig = createHmac('sha256', SECRET).update(body).digest('hex')

const res = await fetch(WEBHOOK_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Signature': sig,
    'X-Timestamp': Math.floor(Date.now() / 1000).toString(),
  },
  body,
})
console.log(res.status, await res.text())

Intégration d'un consommateur

Lorsque vous accordez à un tiers l'accès à l'un de vos déclencheurs API Prompt, partagez exactement quatre éléments — et rien d'autre :

1. URL du webhook — https://staging-app.mybotbox.com/api/webhooks/prompt/<path>
2. Secret HMAC — la valeur que vous avez saisie dans le champ « HMAC secret »
3. Nom de l'en-tête de signature — X-Signature (par défaut) ou le nom personnalisé que vous avez défini
4. Contrat du corps — la forme { prompt: string, context?: object, metadata?: object }, ainsi que votre maxPromptLength configuré et si requireContext est activé

Comment partager le secret en toute sécurité

Le secret HMAC authentifie chaque appel. S'il est compromis, n'importe qui peut déclencher votre workflow avec des prompts arbitraires. Traitez-le comme un mot de passe de base de données.

À ne pas faire :

• L'envoyer par e-mail ou Slack en clair
• Le coller dans des documents partagés (Notion, Confluence, Google Docs)
• Le committer dans un dépôt, même privé
• Réutiliser le même secret entre staging et production

À faire, par ordre de préférence :

1. Élément partagé 1Password / Bitwarden — limité à l'adresse e-mail du destinataire, avec une expiration. La plupart des équipes en disposent déjà.
2. Message chiffré — Signal, ou gpg --encrypt --recipient <them@…> puis envoyer le texte chiffré via n'importe quel canal.
3. Lien à usage unique — https://onetimesecret.com ou un équivalent auto-hébergé. Consultation unique, auto-destruction après quelques minutes.
4. Le dicter lors d'un appel vidéo — le destinataire le colle directement dans son gestionnaire de secrets, puis vous fermez tous les deux le partage. Rien n'est écrit.

Hygiène opérationnelle

• Générez un secret robuste : openssl rand -hex 32 (256 bits). Les valeurs de type 1234567890 conviennent pour un premier test rapide, mais faites une rotation avant tout partage externe.
• Effectuez une rotation tous les 90 jours, ou immédiatement si un consommateur se déconnecte. Mettez à jour le secret dans l'interface du déclencheur, enregistrez, puis notifiez votre consommateur. Les anciennes signatures cessent de fonctionner dès l'enregistrement — si vous avez besoin d'une période de grâce, exécutez deux déclencheurs en parallèle pendant la transition.
• Indiquez aux consommateurs où stocker le secret : leur gestionnaire de secrets (AWS Secrets Manager / GCP Secret Manager / HashiCorp Vault / Doppler) ou leur store de variables d'environnement CI. Jamais dans les sources.
• Surveillez les logs après une rotation : une soudaine augmentation des erreurs 401 signifie généralement qu'un consommateur n'a pas été informé de la rotation.

Protection contre les rejeux, idempotence et limitation du débit

• Fenêtre de rejeu (mode HMAC uniquement) : rejette les requêtes dont le X-Timestamp est à plus de N secondes de l'heure du serveur. Par défaut 300s, 0 désactive.
• Idempotence : lorsqu'elle est activée, les requêtes en double (correspondance sur X-Idempotency-Key, id du corps ou condensé du corps) retournent 200 { status: "duplicate" } sans relancer le workflow. Fenêtre de déduplication de 7 jours.
• Limitation du débit par appelant : par défaut 20 requêtes/min, indexée sur l'identité de l'appelant dérivée. Déclenche un 429 avec l'en-tête Retry-After en cas de dépassement.

Protections contre l'injection de prompt

Lorsqu'elles sont activées (par défaut activées), la plateforme analyse le prompt par rapport à une liste de blocage restreinte de schémas d'injection courants (ignore previous instructions, préfixe system:, marqueurs de template de chat, etc.) et expose le résultat via guardrailsTriggered + matchedInjectionPatterns. Les protections sont non bloquantes — le workflow s'exécute quand même — vous pouvez donc décider par workflow de refuser, de router vers une révision humaine, ou de continuer.

Structure typique d'un workflow

1. Déclencheur API Prompt (ce bloc) — l'appelant envoie { prompt, context }.
2. Bloc Agent / LLM — reçoit <apiprompt1.prompt> et <apiprompt1.context>, planifie les prochaines actions via l'appel d'outils.
3. Blocs d'action en aval (e-mail, base de données, APIs tierces) — exécutent le plan.
4. Bloc Response — retourne le résumé de l'agent à l'appelant initial.

Exemple — Résumeur de PDF

curl -X POST https://staging-app.mybotbox.com/api/webhooks/prompt/abc123 \
  -H 'Authorization: Bearer $MBB_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Summarize these PDFs into bullet points and email to team@example.com",
    "context": {
      "pdf_gcs_paths": [
        "gs://my-bucket/docs/report-2026-q1.pdf",
        "gs://my-bucket/docs/report-2026-q2.pdf"
      ]
    }
  }'

Configuration du workflow :

• Bloc API Prompt → bloc Agent (Claude Haiku) avec les outils [gcs_read_file, gmail_send] et le prompt système "Follow the user's instructions. Use tools as needed.".
• Message utilisateur de l'agent : <apiprompt1.prompt>\n\nContext: <apiprompt1.context>.

Vérification avec les scripts fournis

# Bearer token mode (recommended default).
bun apps/sat/tests/staging/triggers/api_prompt/verify.ts \
  https://staging-app.mybotbox.com/api/webhooks/prompt/<path> \
  --secret=<bearer-token>

# Or HMAC mode.
bun apps/sat/tests/staging/triggers/api_prompt/verify.ts \
  https://staging-app.mybotbox.com/api/webhooks/prompt/<path> \
  --hmac=<hmac-secret>

python3 apps/sat/tests/staging/triggers/api_prompt/verify.py \
  https://staging-app.mybotbox.com/api/webhooks/prompt/<path> \
  --secret=<bearer-token>

Source : apps/sat/tests/staging/triggers/api_prompt/.

Quand utiliser API Prompt plutôt que Generic Webhook

Generic Webhook est plus simple et plus rapide quand les champs du corps correspondent 1:1 aux variables du workflow. Utilisez API Prompt quand vous souhaitez que le LLM soit le routeur.