Webhooks de dépôt

À propos des webhooks de dépôt

Les webhooks de référentiel vous permettent de recevoir des charges utiles HTTP POST chaque fois que certains événements se produisent dans un référentiel. Vous pouvez utiliser l’API REST pour gérer les webhooks de dépôt, d’organisation et d’application. Vous pouvez lister les livraisons d’un webhook, ou obtenir et refaire une livraison individuelle d’un webhook, qui peut être intégré dans une application ou un service externe. Vous pouvez également utiliser l’API REST pour changer la configuration du webhook. Par exemple, vous pouvez modifier l’URL de charge utile, le type de contenu, la vérification SSL et le secret. Pour plus d'informations, consultez les pages suivantes :

Si vous souhaitez configurer un seul webhook pour recevoir des événements de tous les dépôts de votre organisation, consultez la documentation de notre API REST pour les Webhooks d’organisation.

Outre l’API REST, GitHub peut également servir de hub PubSubHubbub pour les référentiels.

Réception de webhooks

Pour que GitHub envoie des charges utiles de webhook, votre serveur doit être accessible à partir d’Internet. Nous vous suggérons également vivement d’utiliser SSL afin que nous puissions envoyer des charges utiles chiffrées via HTTPS.

En-têtes de webhook

GitHub envoie plusieurs en-têtes HTTP pour différencier les types d’événements et les identificateurs de charge utile. Consultez En-têtes de webhook pour plus de détails.

PubSubHubbub

GitHub peut également servir de hub PubSubHubbub pour tous les référentiels. PSHB est un protocole de publication/abonnement simple qui permet aux serveurs de s’inscrire pour recevoir des mises à jour lorsqu’une rubrique est mise à jour. Les mises à jour sont envoyées avec une requête HTTP POST à une URL de rappel. Les URL de rubrique pour les pushs d’un référentiel GitHub sont au format suivant :

https://github.com/{owner}/{repo}/events/{event}

L’événement peut être n’importe quel événement de webhook disponible. Pour plus d’informations, consultez « Événements et charges utiles du webhook ».

Format de la réponse

Le format par défaut est ce que les hooks post-réception existants doivent attendre : un corps JSON envoyé en tant que paramètre payload dans un POST. Vous pouvez également spécifier de recevoir le corps JSON brut avec un en-tête Accept ou une extension .json.

Accept: application/json
https://github.com/{owner}/{repo}/events/push.json

URL de rappel

Les URL de rappel peuvent utiliser le protocole HTTP.

# Send updates to a PostBin bin
https://www.toptal.com/developers/postbin/123

Abonnement

Le point de terminaison PubSubHubbub de GitHub est : https://api.github.com/hub. Une requête réussie avec curl ressemble à :

curl -u "user" -i \
  https://api.github.com/hub \
  -F "hub.mode=subscribe" \
  -F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
  -F "hub.callback=https://www.toptal.com/developers/postbin/123"

Les requêtes PubSubHubbub peuvent être envoyées plusieurs fois. Si le hook existe déjà, il sera modifié en fonction de la requête.

Paramètres

Nom	Type	Description
`hub.mode`	`string`	Requis. `subscribe` ou `unsubscribe`.
`hub.topic`	`string`	Requis. URI du référentiel GitHub auquel s’abonner. Le chemin d’accès doit être au format `/{owner}/{repo}/events/{event}`.
`hub.callback`	`string`	URI pour recevoir les mises à jour de la rubrique.
`hub.secret`	`string`	Clé secrète partagée qui génère une signature de hachage du contenu du corps sortant. Vous pouvez vérifier qu’une transmission de type push provient de GitHub en comparant le corps de la requête brute au contenu de `X-Hub-Signature` ou `X-Hub-Signature-256`des en-têtes. Pour plus d’informations, consultez la documentation PubSubHubbub.