Webhooks

Ophelix prévient votre serveur à chaque changement d’état, sans que vous interrogiez l’API. Un point de terminaison (WebhookEndpoint, we_…) est l’adresse qui reçoit les événements.

Droits de clé : webhooks:read et webhooks:write.

Cycle de vie

Je veux…

Déclarer un point de terminaison

curl https://api.ophelix.fr/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://exemple.fr/hook", "enabled_events": ["claim.*", "coverage.retrieved"]}'

La réponse contient secret, qui commence par whsec_ et ne s’affiche qu’une fois. enabled_events accepte un type exact, un joker claim.*, ou *. En production, l’adresse est en HTTPS. Une adresse de réseau privé est refusée.

Vérifier la signature

Chaque livraison porte l’en-tête Ophelix-Signature: t=1793890000,v1=5257a8…. v1 est le HMAC-SHA256, en hexadécimal, de t, d’un point et du corps brut, avec votre secret. Rejetez une livraison dont t date de plus de cinq minutes : elle peut être rejouée.

function verify(string $body, string $header, string $secret): bool
{
    if (preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m) !== 1) {
        return false;
    }
 
    return abs(time() - (int) $m[1]) <= 300
        && hash_equals(hash_hmac('sha256', "{$m[1]}.{$body}", $secret), $m[2]);
}

import { createHmac, timingSafeEqual } from 'node:crypto'
 
export function verify(body: string, header: string, secret: string): boolean {
  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header)
  if (!match) return false
  const [, timestamp, signature] = match
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const expected = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex')
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
}

Vérifiez le corps brut, avant tout décodage JSON.

Répondre

Répondez par un code 2xx en moins de dix secondes, et traitez l’événement ensuite. Une redirection compte comme un échec.

Reprises

Une livraison échouée est retentée après 1 minute, 5 minutes, 30 minutes, 2 heures, 6 heures, 12 heures, 24 heures, puis environ 27 heures : trois jours en tout. Ensuite, le point de terminaison est désactivé et vos administrateurs sont alertés.

Diagnostiquer

GET /v1/webhook-endpoints/{id}/deliveries donne chaque tentative : code de réponse, durée, corps envoyé et corps reçu. POST /v1/webhook-endpoints/{id}/resend renvoie un événement.

Événements

webhook_endpoint.test part à la demande, à ce seul point. Le catalogue complet : Événements.

Pièges

• Une même livraison peut arriver deux fois : dédoublonnez sur l’id de l’événement.
• L’ordre n’est pas garanti. Fiez-vous à l’état de l’objet relu, pas à l’ordre d’arrivée.
• Un secret renouvelé vaut aussitôt. L’ancien cesse de signer : déployez le nouveau d’abord.
• Test et production sont séparés. Un point créé avec une clé de test ne reçoit que les événements de test.
• Sur un poste de test, l’agent relaie les événements vers localhost : voir Postes.