Webhook Setup

{
    "repo_name": "username/repository",
    "repo_url": "https://github.com/username/repository",
    "ref": "refs/heads/main",
    "commit_sha": "abc123d",
    "commit_message": "Fix reentrancy vulnerability",
    "commit_url": "https://github.com/username/repository/commit/abc123d",
    "author": "John Doe",
    "solidity_changed": true,
    "modified_files": ["contracts/Token.sol", "README.md"]
}
```python

## Security

### Signature Verification

The bot verifies all webhook requests using HMAC-SHA256 (via `webhook.py:49`):

```python
def _verify_signature(self, payload: bytes, signature: str) -> bool:
    """Verify GitHub webhook signature."""
    if not signature.startswith("sha256="):
        return False
    
    expected_signature = "sha256=" + hmac.new(
        self.webhook_secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)
```python

<Warning>
  **Requests with invalid signatures are rejected with HTTP 401** (via `webhook.py:72`).
  
  This prevents:
  - Unauthorized webhook triggers
  - Malicious payload injection
  - Replay attacks
</Warning>

### Best Practices

<AccordionGroup>
  <Accordion title="Use strong webhook secrets">
    Generate cryptographically secure secrets (minimum 32 characters):

    - Use `openssl rand -hex 32` on Linux/Mac
    - Use `python -c "import secrets; print(secrets.token_hex(32))"` in Python
  </Accordion>
  
  <Accordion title="Enable HTTPS">
    Always use HTTPS for webhook endpoints in production:
    - Prevents man-in-the-middle attacks
    - Protects webhook secret in transit
    - Required by many GitHub organization policies
    
    <Tip>
      Get free SSL certificates from [Let's Encrypt](https://letsencrypt.org/)
    </Tip>
  </Accordion>
  
  <Accordion title="Restrict to GitHub IPs">
    Optionally restrict webhook endpoint to GitHub's IP ranges for additional security.

    <Note>
      GitHub's IP ranges: [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses)
    </Note>
  </Accordion>
  
  <Accordion title="Monitor webhook logs">
    Set up alerts for:
    - Repeated signature verification failures
    - Unusual event frequencies
    - Webhook errors
    - Database anomalies or corruption
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="GitHub shows delivery failure">
    **Symptoms**: Red X in Recent Deliveries
    
    **Common causes**:
    1. **Endpoint not accessible**
       - Check firewall rules
       - Verify bot is running
       - Test with: `curl http://your-url/webhook/github`
    
    2. **SSL/TLS issues**
       - Verify certificate is valid
       - Check for self-signed certificate errors
    
    3. **Timeout**
       - Bot taking too long to respond
       - Check bot logs for errors
       - Increase GitHub timeout if needed
  </Accordion>
  
  <Accordion title="Signature verification failing">
    **Symptoms**: Logs show "Invalid webhook signature"
    
    **Causes**:
    1. **Secret mismatch**
       - Verify `WEBHOOK_SECRET` matches GitHub configuration
       - Check for extra whitespace or newlines
    
    2. **Proxy modifying payload**
       - Ensure reverse proxy doesn't alter request body
       - Check `X-Hub-Signature-256` header is forwarded
    
    **Debug**:
    - Check secret in container: `docker-compose exec audit-bot env | grep WEBHOOK_SECRET`
    - Test signature locally: `echo -n '{"test":true}' | openssl dgst -sha256 -hmac "your_secret"`
  </Accordion>
  
  <Accordion title="Events not triggering actions">
    **Symptoms**: Webhook received but no tweets/audits
    
    **Check**:
    1. **Bot logs for errors**
       - Run: `docker-compose logs -f | grep -i error`
    
    2. **Event type**
       - Only `push` events trigger actions
       - Verify event type in GitHub delivery details
    
    3. **Callbacks registered**
       - Check `on_push` and `on_solidity_change` are configured
       - See `webhook.py:206` for callback setup
  </Accordion>
  
  <Accordion title="Health check passing but webhooks failing">
    **Possible causes**:
    1. **Reverse proxy configuration**
       - Ensure `/webhook/github` path is proxied correctly
       - Check headers are forwarded
    
    2. **Request method**
       - Webhooks require POST method
       - Health check uses GET method
    
    **Test**: Send a POST request to your webhook endpoint with GitHub headers to verify it responds correctly.
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Multiple Repositories

Set up webhooks for multiple repositories using the same bot instance:

1. Configure webhook in each repository (same settings)
2. All repositories send to same URL
3. Bot handles all events through single endpoint

### Custom Event Handling

Modify webhook behavior by editing callback functions in `webhook.py:206`:

```python
def on_push(event_data: dict):
    """Custom push event handler."""
    # Add your custom logic here
    pass

def on_solidity_change(event_data: dict):
    """Custom Solidity change handler."""
    # Add your custom logic here
    pass
```python

### Webhook Testing

Use GitHub's webhook testing features:

1. Go to webhook settings
2. Click **"Recent Deliveries"**
3. Click on any delivery
4. Click **"Redeliver"** to resend the event

<Tip>
  This is useful for debugging without making actual commits.
</Tip>

## Next Steps

- [Configuration Guide](/guides/configuration) - Configure webhook settings
- [Troubleshooting](/guides/troubleshooting) - Common webhook issues
- [Deployment Guide](/guides/deployment) - Production webhook setup