Webhooks > Sécurité et traitement


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.


En-têtes de chaque webhook

  • webhook-id L'identifiant de ce message. Il reste le même à chaque nouvelle tentative; utilisez-le donc pour repérer un webhook que vous avez déjà traité.
  • webhook-timestamp Moment où cette tentative a été envoyée, en secondes depuis 1970 (heure Unix).
  • webhook-signature Envoyé uniquement lorsque la signature est activée. Il contient v1,, puis la signature. Tant qu'un ancien secret est encore actif après un changement, il y a deux signatures, séparées par une espace.

Activer la signature

Créer un secret de signature pour le site :

POST
{base_url}/api/v4/site/{site_id}/webhook/signingSecret/rotate

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é.

Changer le secret

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.

Vérifier ou désactiver la signature

GET
{base_url}/api/v4/site/{site_id}/webhook/security

Indique si la signature et l'en-tête personnalisé sont activés. Il ne retourne jamais de secret.

POST
{base_url}/api/v4/site/{site_id}/webhook/signingSecret/remove

Arrête la signature et supprime tous les secrets du site.


Vérifier un webhook

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.

Avec la bibliothèque standardwebhooks
			
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 :

  1. Rejetez le webhook si webhook-timestamp s'écarte de plus de quelques minutes de l'heure actuelle. Cela empêche qu'un ancien webhook vous soit renvoyé.
  2. Joignez webhook-id, webhook-timestamp et le corps brut en plaçant un point entre chacun.
  3. Retirez whsec_ du début de votre secret et décodez le reste depuis le base64. C'est la clé.
  4. Signez le texte joint avec HMAC-SHA256 à l'aide de cette clé, puis encodez le résultat en base64.
  5. Acceptez le webhook s'il correspond à une entrée v1, dans webhook-signature. Comparez en temps constant.
Sans bibliothèque (Node.js)
			
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)
	})
}


		

En-tête personnalisé

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.

POST
{base_url}/api/v4/site/{site_id}/webhook/authHeader/set

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.

POST
{base_url}/api/v4/site/{site_id}/webhook/authHeader/remove

Arrête l'envoi de l'en-tête.


Gestion des webhooks

  • Répondez rapidement. Répondez avec n'importe quel statut 2xx dès que le webhook est stocké en toute sécurité, puis effectuez le traitement long ensuite. Un webhook sans réponse 2xx dans les 30 secondes est considéré comme échoué et est renvoyé.
  • Attendez-vous à des doublons. Un même webhook peut arriver plus d'une fois. Ignorez tout webhook-id que vous avez déjà traité.
  • Attendez-vous à ce qu'ils arrivent dans le désordre. Un webhook renvoyé peut arriver après un plus récent pour le même enregistrement. Lorsque l'ordre est important, relisez l'enregistrement avec son point de terminaison Get.
  • Vérifiez la signature avant d'agir sur un webhook.

Consultez Webhooks > Introduction pour savoir quand les nouvelles tentatives ont lieu.