Quiconque découvre l'URL de votre webhook peut lui envoyer des requêtes. Activez la signature pour que votre système puisse confirmer qu'un webhook provient bien de Hyfin et n'a pas été modifié en cours de route. La signature suit la spécification Standard Webhooks; ses bibliothèques de vérification fonctionnent donc telles quelles.
Créer un secret de signature pour le site :
Avec un corps vide, Hyfin crée un secret et le retourne une seule fois, sous la forme data.secret. Conservez-le en lieu sûr. Il ne pourra pas être relu plus tard. Vous pouvez plutôt envoyer le vôtre, sous la forme secret : whsec_ suivi de 24 à 64 octets aléatoires en base64. Un secret que vous envoyez n'est pas retourné.
Appelez de nouveau le même point de terminaison pour remplacer le secret. L'ancien secret continue de signer en parallèle du nouveau pendant 24 heures, ce qui vous permet de basculer votre système sans rejeter de webhooks. Définissez previousSecretExpiresInHours pour modifier cette période, de 0 (cesser d'utiliser l'ancien secret immédiatement) à 168 heures.
Indique si la signature et l'en-tête personnalisé sont activés. Il ne retourne jamais de secret.
Arrête la signature et supprime tous les secrets du site.
Le moyen le plus simple est d'utiliser une bibliothèque Standard Webhooks. Il en existe pour JavaScript, Python, Go, Java, Ruby, PHP et .NET. Transmettez le corps brut exactement tel qu'il est arrivé, avant toute analyse JSON.
import { Webhook } from 'standardwebhooks'
// Throws when the signature or timestamp is wrong.
const payload = new Webhook(process.env.WEBHOOK_SECRET).verify(rawBody, request.headers)
Pour le vérifier vous-même :
import crypto from 'node:crypto'
export function verifyWebhook(secret, headers, rawBody) {
const id = headers['webhook-id']
const timestamp = Number(headers['webhook-timestamp'])
if (!id || !Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 5 * 60) return false
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest()
return (headers['webhook-signature'] ?? '').split(' ').some(entry => {
const [version, signature = ''] = entry.split(',')
const received = Buffer.from(signature, 'base64')
return version === 'v1' && received.length === expected.length && crypto.timingSafeEqual(received, expected)
})
}
Si votre système ne peut vérifier qu'un en-tête fixe, par exemple à une passerelle d'API, Hyfin peut envoyer un en-tête de votre choix avec chaque webhook. Cela fonctionne avec ou sans signature, mais la signature est plus sûre, car la valeur ne change jamais.
Envoyez name et value. La valeur doit contenir de 16 à 2 048 caractères ASCII visibles et peut contenir des espaces au milieu. Le nom ne peut pas commencer par webhook- ni être un en-tête que chaque requête contient déjà, comme Content-Type ou Host.
Arrête l'envoi de l'en-tête.
Consultez Webhooks > Introduction pour savoir quand les nouvelles tentatives ont lieu.