Intégrations Botillon

Sur la fiche de son bot (espace propriétaire), le propriétaire choisit votre service. Botillon génère alors un connection_id unique et un webhook_secret (préfixe whs_), puis envoie un POST à votre URL de configuration avec l'événement integration.create.

POST {config_url}
Content-Type: application/json

{
  "type": "integration.create",
  "data": {
    "connection_id": "128379182731",
    "webhook_secret": "whs_abcd…",
    "project": { "id": "42", "platform": "discord", "platform_id": "3949…", "type": "bot" },
    "user": { "id": "7", "platform_id": "1234…", "name": "username", "avatar_url": "…" }
  }
}

Vous persistez la connexion puis répondez avec l'URL qui recevra les webhooks et les scopes d'événements souhaités :

{
  "webhook_url": "https://your.bot/webhooks/botillon",
  "routes": ["vote.create", "like.create", "comment.create"]
}

webhook_url doit être en HTTPS. Les routes sont limitées aux scopes supportés (voir plus bas).

À chaque événement, Botillon envoie un POST signé à votre endpoint. Vérifiez systématiquement la signature avant de traiter le payload, puis répondez 2xx sous 5 secondes.

Headers :
  x-botillon-signature: t={timestamp},v1={hmac_sha256_hex}
  x-botillon-trace:     bl_…

Body (vote.create) :
{
  "type": "vote.create",
  "data": {
    "id": "1787…",
    "weight": 1,
    "created_at": "2026-08-27T10:00:00Z",
    "expires_at": "2026-08-27T22:00:00Z",
    "query": {},
    "user": { "id": "7", "platform_id": "1234…", "name": "username", "avatar_url": "…" },
    "project": { "id": "42", "type": "bot", "platform": "discord", "platform_id": "3949…" }
  }
}

Quand l'utilisateur déconnecte, Botillon envoie integration.delete à votre URL de configuration. Répondez 2xx et nettoyez la connexion de votre côté.

{ "type": "integration.delete", "data": { "connection_id": "128379182731" } }

La signature est un HMAC SHA-256 de {timestamp}.{corps brut}, clé = votre webhook_secret. Comparez en temps constant et rejetez toute requête invalide.

import crypto from 'node:crypto';

function verify(rawBody, signature, secret) {
  const [tPart, v1Part] = signature.split(',');
  const timestamp = tPart.split('=')[1];
  const received = v1Part.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}