# Webhook Testing Guide
## 🧪 Testing Webhooks with Real Services
This guide provides step-by-step instructions for testing CodePilot MCP webhooks with actual external services.
## 🚀 Prerequisites
1. **Deploy CodePilot MCP** to a publicly accessible URL (required for webhooks)
2. **Install ngrok** for local testing (alternative to deployment)
3. **Configure webhook secrets** in your environment variables
### Option A: Deploy to Cloud (Recommended)
```bash
# Deploy to Google Cloud Run
gcloud run deploy codepilot-mcp \
--source . \
--platform managed \
--region us-central1 \
--allow-unauthenticated
# Get your public URL
gcloud run services describe codepilot-mcp --region=us-central1 --format="value(status.url)"
```
### Option B: Use ngrok for Local Testing
```bash
# Install ngrok
npm install -g ngrok
# Start your local server
npm run dev
# In another terminal, expose webhook port
ngrok http 3001
# Note the public URL (e.g., https://abc123.ngrok.io)
```
## 🐙 GitHub Webhooks
### 1. Configure GitHub Webhook
1. Go to your repository → Settings → Webhooks
2. Click "Add webhook"
3. Set **Payload URL**: `https://your-domain.com/webhooks/github`
4. Set **Content type**: `application/json`
5. Set **Secret**: Your `GITHUB_WEBHOOK_SECRET` from `.env`
6. Select events:
- ✅ Push events
- ✅ Pull requests
- ✅ Issues
- ✅ Issue comments
- ✅ Pull request reviews
### 2. Test GitHub Webhook
```bash
# Create a test issue to trigger webhook
curl -X POST \
-H "Authorization: token $GITHUB_TOKEN" \
-H "Accept: application/vnd.github.v3+json" \
https://api.github.com/repos/OWNER/REPO/issues \
-d '{
"title": "Test webhook integration",
"body": "This issue was created to test the CodePilot MCP webhook integration."
}'
# Check your webhook service logs for the received event
```
### 3. Verify Webhook Delivery
1. Go to your repository → Settings → Webhooks
2. Click on your webhook
3. Check "Recent Deliveries" tab
4. Verify successful delivery (green checkmark)
## 📝 Notion Webhooks
### 1. Set Up Notion Integration
1. Go to [Notion Developers](https://developers.notion.com/)
2. Create new integration
3. Get your **Internal Integration Token**
4. Add to workspace and grant permissions
### 2. Configure Notion Webhook
```bash
# Create a webhook subscription (requires Notion API)
curl -X POST https://api.notion.com/v1/webhooks \
-H "Authorization: Bearer $NOTION_TOKEN" \
-H "Content-Type: application/json" \
-H "Notion-Version: 2022-06-28" \
-d '{
"url": "https://your-domain.com/webhooks/notion",
"filters": {
"property": "object",
"values": ["page", "database"]
}
}'
```
### 3. Test Notion Webhook
```bash
# Create a test page to trigger webhook
curl -X POST https://api.notion.com/v1/pages \
-H "Authorization: Bearer $NOTION_TOKEN" \
-H "Content-Type: application/json" \
-H "Notion-Version: 2022-06-28" \
-d '{
"parent": { "database_id": "YOUR_DATABASE_ID" },
"properties": {
"Name": {
"title": [
{
"text": {
"content": "Test Webhook Page"
}
}
]
}
}
}'
```
## 📅 Google Calendar Webhooks
### 1. Set Up Calendar Notifications
```bash
# Set up a watch request for calendar events
curl -X POST \
"https://www.googleapis.com/calendar/v3/calendars/YOUR_CALENDAR_ID/events/watch" \
-H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "codepilot-webhook-channel",
"type": "web_hook",
"address": "https://your-domain.com/webhooks/calendar",
"params": {
"ttl": "3600"
}
}'
```
### 2. Test Calendar Webhook
```bash
# Create a test event
curl -X POST \
"https://www.googleapis.com/calendar/v3/calendars/YOUR_CALENDAR_ID/events" \
-H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"summary": "Test Webhook Event",
"start": {
"dateTime": "2025-07-06T10:00:00-07:00",
"timeZone": "America/Los_Angeles"
},
"end": {
"dateTime": "2025-07-06T11:00:00-07:00",
"timeZone": "America/Los_Angeles"
}
}'
```
## 💬 Slack Webhooks (Event Subscriptions)
### 1. Configure Slack App
1. Go to [Slack API](https://api.slack.com/apps)
2. Create new app or select existing
3. Go to **Event Subscriptions**
4. Enable events and set **Request URL**: `https://your-domain.com/webhooks/slack`
5. Subscribe to bot events:
- ✅ `app_mention`
- ✅ `message.channels`
- ✅ `team_join`
### 2. Test Slack Webhook
```bash
# Test URL verification (Slack will send this first)
curl -X POST https://your-domain.com/webhooks/slack \
-H "Content-Type: application/json" \
-d '{
"token": "verification_token",
"challenge": "test_challenge",
"type": "url_verification"
}'
# Should respond with: {"challenge": "test_challenge"}
```
### 3. Test Real Slack Events
1. Install your Slack app to a workspace
2. Mention your bot in a channel: `@YourBot hello`
3. Check webhook service logs for received events
## 🔧 Custom Webhook Testing
### Test Custom Webhook Endpoint
```bash
# Test custom webhook with any source
curl -X POST https://your-domain.com/webhooks/custom/my-service \
-H "Content-Type: application/json" \
-H "X-Event-Type: user.created" \
-d '{
"event_type": "user.created",
"user_id": "12345",
"email": "test@example.com",
"timestamp": "2025-07-05T12:00:00Z"
}'
```
## 🐛 Debugging Webhook Issues
### 1. Check Webhook Service Logs
```bash
# View real-time logs
docker logs -f codepilot-mcp
# Or for local development
npm run dev
# Watch console output for webhook events
```
### 2. Verify Webhook Signatures
Add debugging to your webhook service:
```typescript
// In src/services/webhook/index.ts
private async handleWebhookEvent(event: WebhookEvent): Promise<void> {
console.log('🔗 Webhook received:', {
source: event.source,
event: event.event,
payload: JSON.stringify(event.payload, null, 2),
signature: event.signature,
timestamp: event.timestamp
});
// ...existing code...
}
```
### 3. Test Webhook Endpoints Individually
```bash
# Health check
curl https://your-domain.com/health
# List recent webhook events
curl https://your-domain.com/webhooks/events
# Test each webhook endpoint
curl -X POST https://your-domain.com/webhooks/github \
-H "Content-Type: application/json" \
-d '{"test": true}'
```
### 4. Validate Environment Variables
```bash
# Check that webhook secrets are set
echo $GITHUB_WEBHOOK_SECRET
echo $SLACK_WEBHOOK_SECRET
echo $NOTION_WEBHOOK_SECRET
# Verify service tokens
echo $GITHUB_TOKEN
echo $SLACK_BOT_TOKEN
echo $NOTION_TOKEN
```
## 📊 Monitoring Webhook Performance
### 1. Dashboard Monitoring
1. Open dashboard at `https://your-domain.com`
2. Check **Recent Activity** section
3. Monitor **System Health** for webhook service status
4. View **Performance Metrics** for webhook response times
### 2. Set Up Alerts
```typescript
// Add to webhook service for monitoring
private async handleWebhookEvent(event: WebhookEvent): Promise<void> {
const startTime = Date.now();
try {
// ...process webhook...
const duration = Date.now() - startTime;
if (duration > 5000) { // Alert if processing takes > 5 seconds
logger.warn('Slow webhook processing', {
source: event.source,
duration,
event: event.event
});
}
} catch (error) {
// Send alert to Slack
await this.slackService?.sendMessage({
channel: '#alerts',
text: `🚨 Webhook error: ${event.source}:${event.event} - ${error.message}`
});
}
}
```
## ✅ Webhook Testing Checklist
- [ ] **Deployment**: Service is publicly accessible
- [ ] **Environment**: All webhook secrets configured
- [ ] **GitHub**: Webhook created and delivering successfully
- [ ] **Slack**: Event subscriptions configured and receiving events
- [ ] **Notion**: Webhook subscriptions active (if using)
- [ ] **Calendar**: Push notifications set up (if using)
- [ ] **Signatures**: Webhook signature verification working
- [ ] **Logging**: Webhook events appearing in logs
- [ ] **Dashboard**: Activity showing in real-time dashboard
- [ ] **Slack Integration**: Notifications being sent to Slack channels
- [ ] **Error Handling**: Failed webhooks properly logged and alerted
## 🔧 Troubleshooting Common Issues
### Issue: Webhook not receiving events
- ✅ Check webhook URL is publicly accessible
- ✅ Verify webhook is properly configured in external service
- ✅ Check webhook service is running and healthy
### Issue: Signature verification failing
- ✅ Verify webhook secret matches in both places
- ✅ Check request headers are being passed correctly
- ✅ Ensure timing-safe comparison is working
### Issue: Events not triggering workflows
- ✅ Check webhook event handler is properly routing events
- ✅ Verify Slack service integration is working
- ✅ Check agent system is processing workflow triggers
### Issue: Dashboard not showing webhook activity
- ✅ Verify WebSocket connection in dashboard
- ✅ Check memory service is storing webhook events
- ✅ Ensure API endpoints are accessible from dashboard
---
**Happy Webhook Testing! 🎯**
