Webhooks

Gilbert dispatche des events HMAC-signés vers vos endpoints quand quelque chose se passe côté votre métier (dossier qualifié, PR ouverte, premier message). Vous vérifiez la signature, vous agissez.

Dernière mise à jour : 7 mai 2026

#Events disponibles

Event	Émis quand
dossier.created	Nouveau dossier prospect, généralement après le premier message d'un visiteur.
dossier.qualified	Une proposition (devis, RDV, qualification) a été enregistrée par Gilbert.
github.sync_completed	Une PR a été ouverte ou mise à jour suite à une synchro Gilbert.
chat.first_message	Premier message d'un nouveau visiteur sur votre embed.

#Format du payload

webhook.body.jsonjson

{
  "event": "dossier.qualified",
  "event_id": "evt_01HV9R2X8M0BR7Y4ZK5C9TKN6F",
  "timestamp": "2026-05-07T14:32:18.000Z",
  "tenant": "votre-tenant",
  "product_context": "solve-learn",
  "data": {
    "dossier_id": "uuid",
    "qualification": {
      "type": "rdv",
      "summary": "RDV démo le 12 mai à 14h",
      "metadata": { /* event-specific */ }
    }
  }
}

#Vérifier la signature

Le header X-Gilbert-Signature contient un hexadécimal SHA-256 calculé sur le body brut avec votre GILBERT_WEBHOOK_SECRET.

webhook.tsts

import crypto from 'node:crypto'
import express from 'express'

const app = express()

// IMPORTANT : on lit le body brut, pas le JSON parsé
// (la signature est calculée sur les octets exacts).
app.post(
  '/webhooks/gilbert',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Gilbert-Signature') ?? ''
    if (!verifySignature(req.body, signature)) {
      return res.status(401).send('invalid signature')
    }

    const event = JSON.parse(req.body.toString('utf8'))
    handleEvent(event) // votre logique métier
    res.status(200).send('ok')
  },
)

function verifySignature(rawBody, signature) {
  const secret = process.env.GILBERT_WEBHOOK_SECRET
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signature)
  if (a.length !== b.length) return false
  return crypto.timingSafeEqual(a, b)
}

#Retry et delivery

2xx= ack. Gilbert considère l'event délivré.
4xx (sauf 408/429)= échec permanent. Pas de retry. L'event est marqué failed côté Gilbert.
408 / 429 / 5xx / timeout = retry avec backoff exponentiel : 30s, 2min, 10min, 1h, 6h, 24h. Abandon après 6 tentatives.
Timeout = 10 secondes. Répondez 2xx vite, faites le travail lourd en background.

#Dev local (tunneling)

Gilbert ne peut pas appeler localhost. Utilisez un tunnel public type ngrok ou cloudflared et enregistrez l'URL publique dans la console Gilbert.

bash

# Exemple ngrok
ngrok http 3000
# → URL publique : https://abcd.ngrok-free.app
# Inscrivez https://abcd.ngrok-free.app/webhooks/gilbert dans la console

Cette page t'a-t-elle aidé ?

Référence