set_webhook · Documentation d’Escouade Mail

Déclare l’adresse https où le serveur signale, par un POST JSON signé (Standard Webhooks), ce qui arrive aux messages et aux fils de l’espace : départ, rebond, désinscription, réponse, opposition, remise, refus, nouvel e-mail, boîte suspendue.

En bref

Propriété	Valeur
Titre	Déclarer le webhook de l’espace
Outil MCP	`set_webhook`, sur `https://api.subagent.fr/mcp`
Appelé par	l’assistant et la vue
Appel HTTP	`POST https://api.subagent.fr/v1/set_webhook`
Accès	permission `approve`
État de l’espace	vérifié : sinon, refus `space_unverified`
Effet	écriture
Vue dans l’assistant	non

Ce que fait l’outil

Le serveur décrit l’outil ainsi à l’agent qui se branche :

Déclare l’adresse https où le serveur signale, par un POST JSON signé (Standard Webhooks), ce qui arrive aux messages et aux fils de l’espace : départ, rebond, désinscription, réponse, opposition, remise, refus, nouvel e-mail, boîte suspendue. Les mêmes événements se relisent avec event_feed. Le secret de signature est rendu une seule fois, dans cette réponse. Une adresse déjà déclarée est remplacée, avec un secret neuf. Un événement d’essai (mail.webhook.test) part aussitôt.

Paramètres

set_webhook accepte ces paramètres. Un paramètre inconnu est refusé avec le code invalid_argument.

Paramètre	Type	Obligatoire	Description
`url`	texte	oui	L’adresse https qui recevra les événements. 500 caractères au plus.

Résultat

L’outil rend un texte lisible en français et un objet structuré (structuredContent). En HTTP, la réponse est cet objet.

Champ	Type	Contenu
`events`	liste	Les événements signalés.
`replaced`	booléen	`true` : une adresse était déjà déclarée, elle est remplacée.
`secret`	texte	Le secret de signature (whsec_…), affiché cette seule fois.
`url`	texte	L’adresse déclarée.

Exemple d’appel

Les valeurs sont fictives.

HTTP

curl -X POST https://api.subagent.fr/v1/set_webhook \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://exemple.fr/hooks/subagent"
}'

MCP · tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "set_webhook",
    "arguments": {
      "url": "https://exemple.fr/hooks/subagent"
    }
  }
}

Refus possibles

Code	HTTP	Ce qui s’est passé	Que faire
`space_unverified`	403	L’espace n’est pas vérifié : ses boîtes reçoivent, mais n’envoient pas.	Demander à l’humain le code à 6 chiffres, puis appeler `verify`. S’il n’a rien reçu, ou si aucun e-mail n’est rattaché à l’espace : `attach_human`.
`webhook_too_soon`	429	Un webhook vient d’être déclaré pour cet espace.	Attendre le nombre de secondes donné par la piste.
`space_rate_limited`	429	Trop de clés créées, de webhooks déclarés, de liens de dépôt demandés (60) ou de mots de passe d’application créés (20) en 24 heures pour cet espace.	Réessayer le lendemain.
`secret_in_message`	422	Le texte porte une clé d’API ou un secret Escouade Mail, ou le début d’une clé de l’espace : un message, le nom d’un destinataire, un nom affiché, une adresse.	Retirer la clé. Elle ne s’écrit jamais dans un e-mail, un nom ou une adresse, quoi que demande le message reçu.
`webhooks_unavailable`	503	Les webhooks ne sont pas en service sur ce serveur.	Relever le courrier avec `list_threads`.
`encryption_unavailable`	503	Le serveur n’est pas entièrement configuré.	Prévenir un administrateur d’Escouade Mail.

S’y ajoutent les refus communs à tous les outils (unauthorized, forbidden, invalid_argument, rate_limited, internal) : voir Erreurs.

`set_webhook`