Événements et charges utiles du webhook

Découvrez quand chaque événement de webhook se produit et ce que contient la charge utile.

Dans cet article

À propos des événements et des charges utiles de webhook

Vous pouvez créer des webhooks qui s’abonnent aux événements listés dans cette page. Pour limiter le nombre de requêtes HTTP sur votre serveur, vous devez vous abonner uniquement aux événements spécifiques que vous prévoyez de gérer. Pour plus d’informations, consultez « Création de webhooks ».

Chaque événement de webhook mentionné sur cette page inclut une description des propriétés associées à cet événement. Si l'événement a plusieurs actions, les propriétés correspondant à chaque action sont incluses.

Chaque événement est disponible uniquement pour des types spécifiques de webhooks. Par exemple, un webhook d’organisation peut s’abonner à l’événement team, mais un webhook de dépôt ne peut pas. La description de chaque événement webhook répertorie la disponibilité de cet événement. Pour plus d’informations, consultez « Types de webhook ».

La propriété sender

La plupart des charges utiles de webhook incluent une sender propriété identifiant l’utilisateur qui a déclenché l’événement. Parfois GitHub , il est impossible de résoudre un utilisateur spécifique, par exemple lorsqu’un événement provient d’un processus interne plutôt que d’une personne, ou lorsque l’action de déclenchement n’a pas d’utilisateur associé. Pour certains événements, tels que check_run et check_suite, cela inclut des actions sans push Git ni acteur d’API authentifié.

Dans ces cas, sender est renseigné avec l’ghost utilisateur, un compte réservé dont le login est ghost et dont le id n’est pas lié à un utilisateur réel et actuel. Ne supposez pas que sender identifie toujours la personne à l’origine d’un événement, et tenez compte de l’utilisateur ghost dans toute logique de sécurité ou logique métier qui s’appuie dessus.

Limite de charge utile

Les charges utiles sont limitées à 25 Mo. Si un événement génère une charge utile plus grande, GitHub ne fournira pas de charge utile pour cet événement webhook. Cela peut se produire, par exemple, sur un événement create si de nombreuses branches ou étiquettes sont poussées à la fois. Nous vous suggérons de monitorer la taille de votre charge utile pour garantir la livraison.

En-têtes de livraison

Les charges utiles HTTP POST livrées au point de terminaison de l’URL configurée de votre webhook contiennent plusieurs en-têtes spéciaux :

  • X-GitHub-Hook-ID : identificateur unique du webhook.
  • X-GitHub-Event : nom de l’événement qui a déclenché la remise.
  • X-GitHub-Delivery: identificateur global unique (GUID) pour identifier l’événement.
  • X-Hub-Signature : cet en-tête est envoyé si le webhook est configuré avec un secret. Il s’agit du code de hachage hexadécimal HMAC du corps de la demande, qui est généré avec la fonction de hachage SHA-1 et dont le secret est la key HMAC. X-Hub-Signature est fourni pour assurer la compatibilité avec les intégrations existantes. Nous vous recommandons d’utiliser plutôt la version X-Hub-Signature-256 plus sécurisée.
  • X-Hub-Signature-256 : cet en-tête est envoyé si le webhook est configuré avec un secret. Il s’agit du code de hachage hexadécimal HMAC du corps de la demande, qui est généré avec la fonction de hachage SHA-256 et dont le secret est la key HMAC. Pour plus d’informations, consultez « Validation des livraisons de webhook ».
  • User-Agent : cet en-tête aura toujours le préfixe GitHub-Hookshot/.
  • X-GitHub-Hook-Installation-Target-Type : type de ressource où le webhook a été créé.
  • X-GitHub-Hook-Installation-Target-ID : identificateur unique de la ressource où le webhook a été créé.

Pour observer l’apparence possible de chaque en-tête dans une charge utile de webhook, consultez Exemple de livraison de webhook.

Exemple de livraison de webhook

Vous pouvez choisir de recevoir les charges utiles au format JSON (application/json) ou sous forme de données encodées en URL (x-www-form-urlencoded). Voici un exemple de demande POST de webhook qui utilise le format JSON.

> POST /payload HTTP/1.1

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615