Claude Code Webhook Implementation Guide

Webhooks enable event-driven architectures that let Claude Code respond to external events in real-time. This guide covers practical webhook implementation patterns for developers building integrated workflows with Claude Code.

Understanding Webhooks in Claude Code Context

Webhooks function as HTTP callbacks that trigger specific actions when events occur in external systems. When properly implemented, they allow Claude Code to receive notifications from services like GitHub, Slack, or custom APIs, then execute appropriate responses based on the received payload.

The implementation approach differs from traditional webhook handling because Claude Code operates as an AI agent rather than a static server. This means you can process webhook payloads through natural language instructions, making the integration more flexible than conventional server-side handlers.

Basic Webhook Setup with Node.js

The foundation of webhook implementation requires an HTTP server to receive incoming requests. Here’s a minimal Express.js setup:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const event = req.headers['x-github-event'];
  const payload = req.body;
  
  console.log(`Received event: ${event}`);
  
  if (event === 'push') {
    handlePushEvent(payload);
  } else if (event === 'pull_request') {
    handlePullRequest(payload);
  }
  
  res.status(200).send('OK');
});

function handlePushEvent(payload) {
  const { commits, repository, pusher } = payload;
  console.log(`Push to ${repository.full_name} by ${pusher.name}`);
}

function handlePullRequest(payload) {
  const { action, number, pull_request } = payload;
  console.log(`PR #${number}: ${action}`);
}

app.listen(3000, () => {
  console.log('Webhook listener running on port 3000');
});

This server receives GitHub webhooks and routes them based on event type. The key insight is structuring your handler to dispatch events to specific functions, keeping your code maintainable as webhook complexity grows.

Integrating Claude Code with Webhook Events

To leverage Claude Code’s capabilities within your webhook flow, use the skill system to process incoming payloads. The recommended pattern involves receiving the webhook, then invoking Claude Code with relevant context from the payload.

Consider integrating with the pdf skill when processing document-related webhooks, or the pptx skill for presentation updates. When webhooks notify you of code changes, pair them with the tdd skill to automatically generate tests for modified functions.

Here’s how to structure the integration:

const { spawn } = require('child_process');

function invokeClaudeWithContext(eventType, payload) {
  const prompt = buildPromptForEvent(eventType, payload);
  
  const claude = spawn('claude', [
    '--print',
    prompt
  ]);
  
  let output = '';
  claude.stdout.on('data', (data) => {
    output += data.toString();
  });
  
  claude.stderr.on('data', (data) => {
    console.error('Claude error:', data.toString());
  });
  
  return output;
}

function buildPromptForEvent(type, payload) {
  const templates = {
    'issue_opened': `A new issue was created: "${payload.issue.title}". 
      Body: ${payload.issue.body}
      Provide a summary and suggest labels.`,
    'push': `${payload.commits.length} commits pushed to ${payload.repository.name}.
      Review the changes and identify potential issues.`
  };
  
  return templates[type] || `Event: ${type}`;
}

Handling Authentication and Security

Securing webhooks prevents unauthorized requests from triggering actions in your system. GitHub provides a signature header that validates payload authenticity:

const crypto = require('crypto');

function verifyGitHubSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyGitHubSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  processWebhook(req.body);
  res.status(200).send('OK');
});

Always verify signatures before processing any webhook payload. Store your webhook secret as an environment variable, never commit it to version control.

Practical Use Cases

Automated Code Review

Configure GitHub webhooks to trigger Claude Code review when pull requests are opened. The webhook delivers the diff, and Claude Code analyzes changes for potential issues, style violations, or security concerns.

Documentation Updates

When your documentation repository receives commits, webhooks can notify Claude Code to validate documentation links, check for broken references, or generate updated API documentation using the docx skill.

Incident Response

Integrate monitoring tool webhooks (PagerDuty, OpsGenie) with Claude Code to receive incident alerts. Claude can analyze the incident, gather relevant context from your supermemory skill, and suggest remediation steps.

Project Management Automation

Connect project management webhooks to create tasks, update statuses, or notify team members. Use the internal-comms skill to draft appropriate messages based on the webhook payload.

Best Practices

Idempotency: Design handlers to handle duplicate webhook deliveries gracefully. Store processed event IDs to prevent duplicate processing.
Timeout Handling: External services may retry failed webhooks. Implement exponential backoff and queue processing for reliability.
Logging: Log all incoming webhooks with timestamps, event types, and processing status. This aids debugging and provides audit trails.
Testing: Use tools like ngrok to expose local development endpoints for testing webhooks during development.
Error Handling: Return proper HTTP status codes. Return 200 quickly for acknowledgment, then process asynchronously to avoid timeouts.

Conclusion

Implementing webhooks with Claude Code transforms your AI assistant into an event-driven component of your development workflow. The combination of HTTP callback handlers and Claude Code’s natural language processing creates powerful automation possibilities without sacrificing flexibility.

Start with simple webhook handlers and progressively add complexity as your integration needs grow. The key is maintaining clean separation between webhook reception and Claude Code invocation, ensuring your system remains maintainable and testable.

Built by theluckystrike — More at zovo.one