Skip to content

Commit

Permalink
Add to and reorder GitHub webhook docs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
davidjb committed Mar 22, 2019
1 parent 3156083 commit 851f7d5
Showing 1 changed file with 8 additions and 4 deletions.
12 changes: 8 additions & 4 deletions docs/webhooks.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/<project-name>/<id>/*.
As an example, the URL pattern looks like this: *https://readthedocs.org/api/v2/webhook/<project-name>/<id>/*.

Use this URL when setting up a new webhook with your provider -- these steps vary depending on the provider:

Expand All @@ -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:
Expand Down

0 comments on commit 851f7d5

Please sign in to comment.