Integrating GitHub with Webhooks for Read the Docs

Webhooks allow your GitHub repository to communicate with external services like Read the Docs, triggering builds automatically every time you push changes. Here’s how you can set up a webhook for your project:

1. Obtain Webhook Details from Read the Docs:

   • Go to your project on Read the Docs.

   • Navigate to the Admin section.

   • Click on Integrations from the sidebar menu.

   • You will find a section titled ‘Integration - GitHub incoming webhook’ which contains the Webhook URL and a Secret. Copy these details as you will need them for the GitHub setup.

2. Configure Webhook on GitHub:

   • Access your GitHub repository.

   • Click on the Settings tab.

   • On the left sidebar, click on Webhooks, then on the Add webhook button.

3. Webhook Setup:

   • In the Payload URL field, paste the Webhook URL you copied from Read the Docs.

   • For Content type, select application/x-www-form-urlencoded.

   • In the Secret field, enter the Secret provided by Read the Docs.

   • Enable SSL verification to ensure secure data transmission.

4. Select Trigger Events:

   • Choose which events you would like to trigger this webhook. Typically, you would select ‘Just the push event’ for documentation projects.

5. Activate Webhook:

   • Ensure the Active checkbox is selected to enable the webhook.

   • Click on Add webhook to save and activate the webhook.

6. Verify Webhook Integration:

   • Once the webhook is added, GitHub will send a ping to Read the Docs to test the connection.

   • You can verify the integration by pushing a commit to your repository and checking if a new build is triggered on Read the Docs.

Important: Remember to save your webhook settings on GitHub immediately after adding them. The secret token is sensitive information and should be kept secure. Also, GitHub will not display the secret again after you navigate away from the page.