Webhooks sortants

Configurer un endpoint

Ouvrez une application dans la console développeur, choisissez Webhooks, puis enregistrez une URL HTTPS publique et les familles d’événements nécessaires. Une application peut posséder jusqu’à 10 endpoints. Les événements ne sont envoyés que pour les communautés où son bot est installé. Les destinations privées, loopback et link-local sont refusées. Les redirections ne sont jamais suivies.

Enveloppe de livraison

Chaque callback est une requête HTTP POST application/json. id reste identique entre les tentatives, event nomme l’événement souscrit et data contient le payload original du dispatch Gateway. Renvoyez un statut 2xx en moins de 10 secondes pour l’acquitter.

{
  "id": "<delivery_id>",
  "event": "MESSAGE_CREATE",
  "created_at": "2026-08-30T12:00:00Z",
  "data": { "id": "<message_id>", "content": "Hello" }
}

Vérifier la signature

Lyra envoie X-Lyra-Event, X-Lyra-Delivery, X-Lyra-Timestamp et X-Lyra-Signature-256. Calculez HMAC-SHA256 avec le secret sur les octets UTF-8 de « timestamp.corps_brut_de_la_requête », préfixez le digest hexadécimal en minuscules par v1=, puis comparez en temps constant. Refusez les timestamps anciens avant de lire ou traiter le payload.

import crypto from 'node:crypto'

export function verifyLyraWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-lyra-timestamp']
  const received = headers['x-lyra-signature-256']
  if (!timestamp || !received) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest('hex')
  const left = Buffer.from(expected)
  const right = Buffer.from(received)
  return left.length === right.length && crypto.timingSafeEqual(left, right)
}

Nouvelles tentatives et historique

Les erreurs réseau et les réponses HTTP 408, 425, 429 et 5xx sont retentées avec un délai exponentiel, jusqu’à huit tentatives. Les autres réponses 4xx échouent immédiatement. Les identifiants de livraison permettent un traitement idempotent : enregistrez chaque ID traité avant tout effet de bord. La console expose pendant 30 jours le statut, le nombre de tentatives, le code HTTP, la latence et la dernière erreur.

Endpoints de gestion