Webhook

Définition

Un webhook est un callback HTTP défini par l’utilisateur — lorsqu’un événement se produit, le système source envoie une requête HTTP POST à une URL configurée. C’est un moyen pour une application d’envoyer des données en temps réel à une autre application, éliminant le besoin de polling.

Les webhooks sont parfois appelés « APIs inverses » car ils envoient des données au consommateur au lieu d’attendre que le consommateur les demande.

Webhook vs polling

|| Aspect | Webhook | Polling | |——–|———|———| | Direction | Push (source → consommateur) | Pull (consommateur → source) | | Temps réel | Presque instantané | Dépend de l’intervalle de polling | | Bande passante | Uniquement lors des événements | Constante, même sans données | | Complexité | Le consommateur doit exposer un endpoint | Simple (pas de configuration serveur requise) | | Fiabilité | Dépend de la disponibilité de l’endpoint | Livraison garantie (si retries) | | Cas d’utilisation | Notifications, triggers CI/CD | Vérifications d’état, synchronisation |

Flux de travail Webhook

Événement se produit (ex. GitHub push)
    │
    ▼
Système Source (GitHub/GitLab)
    │
    │ HTTP POST
    │ Content-Type: application/json
    │ Body: { "event": "push", "repo": "...", "ref": "..." }
    ▼
Endpoint Consommateur (votre serveur)
    │
    │ HTTP 200 OK (accuser réception)
    ▼
Traiter l'événement (ex. trigger CI/CD build)

Exemple de payload Webhook (GitHub)

{
  "action": "push",
  "repository": {
    "name": "my-app",
    "owner": { "login": "my-org" }
  },
  "pusher": { "name": "developer", "email": "dev@example.com" },
  "ref": "refs/heads/main",
  "commits": [
    { "sha": "abc123", "message": "fix: resolve login bug" }
  ]
}

Cas d’utilisation Webhook

|| Cas d’utilisation | Source | Consommateur | |———-|——–|———-| | Trigger CI/CD | GitHub/GitLab | Jenkins, GitHub Actions | | Notifications chat | GitHub, Jira, CI | Slack, Discord, Teams | | Traitement de paiement | Stripe, PayPal | Backend e-commerce | | Alertes monitoring | Prometheus, Datadog | PagerDuty, Slack | | Mises à jour CRM | Salesforce, HubSpot | Systèmes internes | | Upload de fichiers | S3, Dropbox | Pipeline de traitement | | Événements d’authentification | Auth0, Okta | Gestion de sessions utilisateur |

Fiabilité des Webhooks

|| Problème | Solution | |——-|———-| | Endpoint hors ligne | Retry avec backoff exponentiel | | Réponse lente | Accuser rapidement, traiter en async | | Duplicatas | Handlers idempotents (vérifier l’ID d’événement) | | Sécurité | Vérifier la signature (HMAC), utiliser des tokens | | Debugging | Logger les payloads, utiliser des outils de test webhook |

Sécurité des Webhooks

# Vérification du secret du webhook GitHub
# La source envoie : X-Hub-Signature-256: sha256=...
# Le consommateur vérifie :
import hmac, hashlib
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
if hmac.compare_digest(expected, received):
    process(payload)

|| Méthode | Description | |——–|————-| | Secret partagé | Secret partagé dans l’en-tête (X-Webhook-Secret) | | Signature HMAC | Signature cryptographique du payload | | TLS | HTTPS pour la sécurité du transport | | Whitelist IP | Restreindre les adresses IP sources | | OAuth | Authentification par token |

Outils de test Webhook

|| Outil | Objectif | |——|———| | ngrok | Exposer un endpoint local pour les tests | | Webhook.site | Endpoint webhook temporaire pour le debugging | | RequestBin | Capturer et inspecter les payloads webhook | | Pipedream | Constructeur de flux webhook visuel | | GitHub webhooks test | Test intégré dans les paramètres du repo |

Limitations des Webhooks

  • L’endpoint doit être accessible publiquement (ou utiliser le tunneling pour le dev local)
  • Pas de livraison garantie sans logique de retry
  • Pas d’ordre intégré (sauf si la source le fournit)
  • Problèmes de firewall/nat pour les consommateurs on-prem
  • Rate limiting peut s’appliquer depuis la source

Termes associés

  • Api — les webhooks triggers les pipelines CI/CD
  • Slack — consommateur webhook populaire pour les notifications
  • Kubernetes — les webhooks implémentent l’architecture event-driven
  • REST — les webhooks utilisent HTTP/REST pour la livraison

Références