Loading...
Loading...
Receive and verify GitHub webhooks. Use when setting up GitHub webhook handlers, debugging signature verification, or handling repository events like push, pull_request, issues, or release.
npx skill4agent add hookdeck/webhook-skills github-webhooksconst crypto = require('crypto');
function verifyGitHubWebhook(rawBody, signatureHeader, secret) {
if (!signatureHeader || !secret) return false;
// GitHub sends: sha256=xxxx
const [algorithm, signature] = signatureHeader.split('=');
if (algorithm !== 'sha256') return false;
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
try {
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
} catch {
return false;
}
}const express = require('express');
const app = express();
// CRITICAL: Use express.raw() - GitHub requires raw body for signature verification
app.post('/webhooks/github',
express.raw({ type: 'application/json' }),
(req, res) => {
const signature = req.headers['x-hub-signature-256']; // Use sha256, not sha1
const event = req.headers['x-github-event'];
const delivery = req.headers['x-github-delivery'];
// Verify signature
if (!verifyGitHubWebhook(req.body, signature, process.env.GITHUB_WEBHOOK_SECRET)) {
console.error('GitHub signature verification failed');
return res.status(401).send('Invalid signature');
}
// Parse payload after verification
const payload = JSON.parse(req.body.toString());
console.log(`Received ${event} (delivery: ${delivery})`);
// Handle by event type
switch (event) {
case 'push':
console.log(`Push to ${payload.ref}:`, payload.head_commit?.message);
break;
case 'pull_request':
console.log(`PR #${payload.number} ${payload.action}:`, payload.pull_request?.title);
break;
case 'issues':
console.log(`Issue #${payload.issue?.number} ${payload.action}:`, payload.issue?.title);
break;
case 'ping':
console.log('Ping:', payload.zen);
break;
default:
console.log('Received event:', event);
}
res.json({ received: true });
}
);import hmac
import hashlib
def verify_github_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
if not signature_header or not secret:
return False
# GitHub sends: sha256=xxxx
try:
algorithm, signature = signature_header.split('=')
if algorithm != 'sha256':
return False
except ValueError:
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature, expected)For complete working examples with tests, see:
- examples/express/ - Full Express implementation
- examples/nextjs/ - Next.js App Router implementation
- examples/fastapi/ - Python FastAPI implementation
| Event | Description |
|---|---|
| Commits pushed to branch |
| PR opened, closed, merged, etc. |
| Issue opened, closed, labeled, etc. |
| Release published |
| GitHub Actions workflow completed |
| Test event when webhook created |
For full event reference, see GitHub Webhook Events
| Header | Description |
|---|---|
| HMAC SHA-256 signature (use this, not sha1) |
| Event type (push, pull_request, etc.) |
| Unique delivery ID |
GITHUB_WEBHOOK_SECRET=your_webhook_secret # Set when creating webhook in GitHub# Install Hookdeck CLI for local webhook testing
brew install hookdeck/hookdeck/hookdeck
# Start tunnel (no account needed)
hookdeck listen 3000 --path /webhooks/github// Generated with: github-webhooks skill
// https://github.com/hookdeck/webhook-skills