Webhooks

Les webhooks envoient chaque entrée du journal d’audit des actions admin (page Audit Log) à une URL que vous contrôlez, dès qu’elle est enregistrée : client créé, modifié ou supprimé, secret régénéré, inscription approuvée ou rejetée, changeset appliqué, etc.

Gérez-les dans Paramètres > Intégrations > Webhooks. Cette page est réservée aux administrateurs de l’instance et aux propriétaires et administrateurs d’organisation. Un webhook appartient à l’organisation où il a été créé.

Ajouter un webhook

Indiquez l’URL, éventuellement une description, et choisissez Tous les événements ou certains. Le secret de signature n’est affiché qu’une fois, à l’ajout : copiez-le à ce moment. Envoyer un test envoie un événement webhook.test et montre le résultat. Vous pouvez désactiver ou supprimer un webhook à tout moment. 10 au plus par organisation.

L’URL doit utiliser https et ne pas contenir d’identifiants. Par défaut, Taco refuse d’envoyer vers des adresses privées, de bouclage ou de lien local (revérifiées à la connexion, pour qu’un hôte ne puisse pas changer de réponse entre-temps) et ne suit jamais les redirections.

Ce qui est envoyé

Un POST avec un corps JSON :

{
  "id": "0d4f…",
  "type": "client.secret.rotate",
  "created_at": "2026-10-02T10:00:00.000Z",
  "organization_id": "org_…",
  "status": "success",
  "actor": { "id": "usr_…", "email": "admin@example.com" },
  "target": { "type": "client", "id": "abc123" },
  "details": {}
}

type est l’action d’audit (client.create, client.secret.rotate, registration.approve… ; le filtre de la page Audit Log les liste), status vaut success ou failure. L’adresse IP et le user agent de l’administrateur ne sont pas envoyés.

En-têtes : X-Taco-Event, X-Taco-Delivery (unique par envoi), X-Taco-Timestamp (secondes Unix) et X-Taco-Signature.

Vérifier la signature

La signature est v1= suivi du HMAC-SHA256 hexadécimal, avec votre secret de signature comme clé, de <timestamp>.<corps brut>. Recalculez-la sur le corps brut, comparez en temps constant et rejetez les horodatages anciens pour empêcher le rejeu.

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret, headers, rawBody) {
  const expected = `v1=${createHmac('sha256', secret)
    .update(`${headers['x-taco-timestamp']}.${rawBody}`)
    .digest('hex')}`
  const given = Buffer.from(headers['x-taco-signature'] ?? '')
  return (
    given.length === expected.length &&
    timingSafeEqual(given, Buffer.from(expected))
  )
}

Envoi et nouvelles tentatives

Toute réponse 2xx vaut pour livrée. Sinon (ou après 10 secondes sans réponse), Taco réessaie après 1 minute, 5 minutes, 30 minutes, 2 heures et 12 heures, puis abandonne au bout de 6 tentatives. Les nouvelles tentatives partent d’une tâche planifiée chaque minute (un déclencheur cron sur Cloudflare). Un envoi peut arriver plusieurs fois : utilisez X-Taco-Delivery pour ignorer les doublons. Les envois sont gardés 30 jours ; la page de paramètres montre les plus récents.