From 851f7d5e0eeac4454acc78e2931dba202fe449d6 Mon Sep 17 00:00:00 2001 From: David Beitey Date: Thu, 21 Mar 2019 03:42:00 +0000 Subject: [PATCH] Add to and reorder GitHub webhook docs This does a small cleanup on the GitHub webhook docs by reordering the instructions in the order which fields are shown to the user on GitHub (reducing jumping around) but also explains the initial "ping" process that GitHub does. It was confusing to see RTD respond with `{"detail":"Unhandled webhook event"}` to a ping, when in fact this is working-as-expected. --- docs/webhooks.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index bbbd3dbce12..4e5bc241946 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -34,7 +34,7 @@ To manually set up a webhook, go to :guilabel:`Admin` > :guilabel:`Integrations` dashboard page and select the integration type you'd like to add. After you have added the integration, you'll see a link to information about the integration. -As an example, the URL pattern looks like this: *readthedocs.org/api/v2/webhook///*. +As an example, the URL pattern looks like this: *https://readthedocs.org/api/v2/webhook///*. Use this URL when setting up a new webhook with your provider -- these steps vary depending on the provider: @@ -50,15 +50,19 @@ GitHub You may need to prepend *https://* to the URL. * For **Content type**, both *application/json* and *application/x-www-form-urlencoded* work -* Select **Let me select individual events**, - and mark **Pushes**, **Branch or tag creation**, and **Branch or tag deletion** events * Leave the **Secrets** field blank -* Finish by clicking **Add webhook** +* Select **Let me select individual events**, + and mark **Branch or tag creation**, **Branch or tag deletion** and **Pushes** events +* Ensure **Active** is enabled; it is by default +* Finish by clicking **Add webhook**. You may be prompted to enter your GitHub password to confirm your action. You can verify if the webhook is working at the bottom of the GitHub page under **Recent Deliveries**. If you see a Response 200, then the webhook is correctly configured. For a 403 error, it's likely that the Payload URL is incorrect. +GitHub will emit an initial HTTP request (`X-GitHub-Event: ping`) upon creating the webhook and you may notice that the Read the Docs responds with `{"detail":"Unhandled webhook event"}` – this is normal and expected. +Push changes to your repository and webhooks will work from this point. + .. note:: The webhook token, intended for the GitHub **Secret** field, is not yet implemented. .. _webhook-integration-bitbucket: