Skip to content

webhook-setup.md

Latest commit

 

History

History
69 lines (47 loc) · 2.37 KB

webhook-setup.md

File metadata and controls

69 lines (47 loc) · 2.37 KB

GitHub Webhook Integration for Automatic Documentation

This guide explains how to set up GitHub webhooks to automatically update repository documentation whenever new code is pushed.

Overview

When you connect a GitHub repository to our system, you can configure a webhook to trigger automatic documentation updates whenever code is pushed to the repository. This eliminates the need to manually click "Generate Docs" in the UI.

Setup Instructions

1. Generate a Webhook Secret

First, generate a secure webhook secret. This helps verify that webhook requests come from GitHub:

# On Linux/Mac
openssl rand -hex 20

# Or use an online generator
# But make sure to use a secure source

2. Configure Environment Variables

Add your webhook secret to the server's .env file:

GITHUB_WEBHOOK_SECRET=your_generated_secret

Make sure your environment also has a valid GitHub token:

GITHUB_TOKEN=your_github_token

3. Set Up the GitHub Webhook

  1. Go to your GitHub repository
  2. Click on "Settings" > "Webhooks" > "Add webhook"
  3. Configure the webhook:
    • Payload URL: https://your-server-url.com/api/webhooks/github
    • Content type: application/json
    • Secret: Enter the same secret you generated earlier
    • Events: Select "Just the push event"
    • Enable SSL verification (recommended)
    • Click "Add webhook"

4. Test the Webhook

  1. Make a small change to your repository and push it to GitHub
  2. GitHub will send a webhook event to your server
  3. Check your server logs to verify that the documentation was generated
  4. Visit the repository details page to see the updated documentation

Webhook Security

  • The webhook endpoint verifies the GitHub signature using your secret
  • Only push events from repositories registered in our system will trigger documentation updates
  • All webhook activities are logged for security monitoring

Troubleshooting

  • Webhook not triggering: Check GitHub's webhook delivery logs in your repository settings
  • Authentication errors: Verify that your webhook secret matches in both GitHub and your server
  • Documentation not updating: Check server logs for errors, ensure GitHub token has sufficient permissions
  • Rate limiting: GitHub API has rate limits. Reduce webhook frequency or use a token with higher limits

If you have any other issues, please contact our support team.