Webhooks expliqués : charges utiles signées et tentatives

Backend2026-11-14TryQuickToolBox

Vous avez construit une API et devez maintenant notifier d'autres services lorsque des événements se produisent. Le polling est inefficace, vous implémentez donc des webhooks. Mais vous réalisez rapidement : comment vous assurer que la charge utile est authentique ? Et si le récepteur est indisponible ? Sans protections adéquates, les webhooks peuvent devenir une faille de sécurité et un cauchemar de fiabilité.

Dans cet article, nous allons parcourir l'essentiel des webhooks, en nous concentrant sur deux aspects critiques : les charges utiles signées pour la sécurité et les mécanismes de tentatives pour la fiabilité. Nous fournirons des exemples de code pratiques et des bonnes pratiques pour vous aider à construire des systèmes de webhooks robustes.

Que sont les webhooks ?

Les webhooks sont des callbacks HTTP définis par l'utilisateur. Ils permettent à un système d'envoyer des données en temps réel à un autre lorsqu'un événement spécifique se produit. Contrairement aux API où vous tirez les données, les webhooks vous poussent les données. Cela les rend idéaux pour les architectures événementielles.

Les cas d'utilisation courants incluent les notifications de paiement (par exemple, Stripe), les déclencheurs CI/CD (par exemple, GitHub) et les plateformes de messagerie (par exemple, Slack). L'émetteur effectue une requête HTTP POST vers une URL fournie par le récepteur, avec une charge utile contenant les détails de l'événement.

Pourquoi sécuriser les webhooks avec des charges utiles signées ?

Les points de terminaison de webhooks sont accessibles publiquement, ce qui les rend vulnérables à l'usurpation d'identité. Un attaquant pourrait envoyer de fausses charges utiles pour déclencher des actions non intentionnelles. Pour éviter cela, les émetteurs signent la charge utile à l'aide d'un secret partagé. Le récepteur vérifie la signature pour garantir l'authenticité et l'intégrité.

La signature implique généralement la génération d'un HMAC (code d'authentification de message basé sur le hachage) de la charge utile à l'aide d'une clé secrète. La signature est envoyée dans un en-tête (par exemple, X-Signature). Le récepteur recalcule le HMAC et le compare à la signature reçue.

Comment implémenter des charges utiles signées

Voyons un exemple simple en Python avec Flask. L'émetteur calcule la signature :

import hmac
import hashlib
import json
import requests

secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()

headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)

Le récepteur vérifie la signature :

from flask import Flask, request, abort
import hmac
import hashlib

app = Flask(__name__)
secret = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data()
    expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    # Traiter la charge utile
    return '', 200

Bonnes pratiques :

Implémenter des tentatives fiables

La livraison de webhooks peut échouer en raison de problèmes réseau, d'indisponibilité du récepteur ou d'erreurs de traitement. Un système robuste doit réessayer les livraisons échouées avec un backoff exponentiel.

Stratégie de tentatives

Approche courante : réessayer jusqu'à N fois avec des délais croissants (par exemple, 1s, 5s, 30s, 5m, 30m). Après avoir épuisé les tentatives, marquez la livraison comme échouée et alertez.

Voici un mécanisme de tentative simple en Python utilisant la bibliothèque requests et tenacity :

from tenacity import retry, stop_after_attempt, wait_exponential
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
    headers = {'X-Signature': signature}
    response = requests.post(url, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return response

Bonnes pratiques pour les tentatives :

Comparaison : charges utiles signées vs authentification de base

ApprocheSécuritéComplexitéProtection contre le rejeu
Authentification de baseFaible (identifiants envoyés à chaque fois)FaibleNon
Charge utile signée (HMAC)ÉlevéeMoyenneOui (avec horodatage)

Étape par étape : construire un émetteur de webhook avec tentatives

  1. Définissez la charge utile de l'événement et incluez un ID d'événement unique et un horodatage.
  2. Calculez la signature en utilisant HMAC-SHA256 sur le corps brut.
  3. Envoyez la requête avec la signature dans un en-tête.
  4. Gérez les échecs en réessayant avec un backoff exponentiel.
  5. Journalisez les livraisons et assurez la visibilité.

Tester les webhooks

Utilisez des outils comme ngrok pour exposer votre serveur local et tester la livraison de webhooks. Vérifiez toujours les signatures dans vos tests pour détecter les problèmes tôt.

FAQ

Qu'est-ce qu'une charge utile signée dans les webhooks ?

Une charge utile signée est une requête de webhook où l'émetteur inclut une signature cryptographique (généralement HMAC) générée avec un secret partagé. Le récepteur vérifie la signature pour confirmer que la requête est authentique et n'a pas été altérée.

Combien de fois dois-je réessayer un webhook échoué ?

Il n'y a pas de nombre fixe, mais la pratique courante est de 3 à 5 tentatives avec un backoff exponentiel. Tenez compte de l'indisponibilité typique de votre récepteur et de la criticité de l'événement. Permettez toujours des tentatives manuelles.

Puis-je utiliser JWT pour les signatures de webhooks ?

Oui, JWT peut être utilisé, mais c'est plus complexe. Les signatures HMAC sont plus simples et suffisantes pour la plupart des cas. Si vous avez besoin d'inclure des revendications, JWT pourrait convenir.

Prêt à tester vos charges utiles de webhook ? Utilisez notre Formateur JSON pour valider et embellir vos charges utiles JSON avant de les envoyer.