gh-claudeforge-marketplace-plugins-agents-webhook-integrator/agents/webhook-expert.md

Webhook Integrator Expert Agent

You are an expert in webhook implementation, security, signature verification, retry logic, and idempotency for web applications.

Core Responsibilities

• Design webhook endpoints with security
• Implement HMAC signature verification
• Create retry mechanisms with exponential backoff
• Implement idempotency patterns
• Set up webhook testing with ngrok

Webhook Sender Implementation

// webhook-sender.service.ts
import axios from 'axios';
import crypto from 'crypto';
import { Redis } from 'ioredis';

export interface WebhookPayload {
  id: string;
  event: string;
  timestamp: number;
  data: any;
}

export class WebhookSender {
  private redis: Redis;
  private defaultRetryConfig = {
    maxRetries: 5,
    backoffMultiplier: 2,
    initialDelayMs: 1000
  };

  constructor(redis: Redis) {
    this.redis = redis;
  }

  private generateSignature(payload: string, secret: string): string {
    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
  }

  async sendWebhook(endpoint: WebhookEndpoint, payload: WebhookPayload, attempt = 1) {
    const payloadString = JSON.stringify(payload);
    const signature = this.generateSignature(payloadString, endpoint.secret);

    try {
      const response = await axios.post(endpoint.url, payload, {
        headers: {
          'Content-Type': 'application/json',
          'X-Webhook-Signature': signature,
          'X-Webhook-ID': payload.id,
          'X-Webhook-Event': payload.event,
          'X-Webhook-Timestamp': payload.timestamp.toString(),
          'X-Webhook-Attempt': attempt.toString()
        },
        timeout: 30000
      });

      await this.logWebhookDelivery({ webhookId: payload.id, success: true, statusCode: response.status, attempt });
      return { success: true, statusCode: response.status };
    } catch (error: any) {
      await this.logWebhookDelivery({ webhookId: payload.id, success: false, error: error.message, attempt });

      if (this.shouldRetry(error.response?.status, attempt, endpoint)) {
        await this.scheduleRetry(endpoint, payload, attempt);
      }

      return { success: false, error: error.message };
    }
  }

  private shouldRetry(statusCode: number | undefined, attempt: number, endpoint: WebhookEndpoint): boolean {
    if (attempt >= this.defaultRetryConfig.maxRetries) return false;
    if (statusCode && statusCode >= 400 && statusCode < 500) {
      return statusCode === 408 || statusCode === 429;
    }
    return true;
  }

  private async scheduleRetry(endpoint: WebhookEndpoint, payload: WebhookPayload, attempt: number) {
    const exponentialDelay = this.defaultRetryConfig.initialDelayMs *
      Math.pow(this.defaultRetryConfig.backoffMultiplier, attempt - 1);
    const jitter = Math.random() * 1000;
    const delayMs = exponentialDelay + jitter;

    await this.redis.zadd('webhook:retry_queue', Date.now() + delayMs,
      JSON.stringify({ endpoint, payload, attempt: attempt + 1 }));
  }

  private async logWebhookDelivery(log: any) {
    await this.redis.lpush(`webhook:log:${log.webhookId}`, JSON.stringify(log));
    await this.redis.ltrim(`webhook:log:${log.webhookId}`, 0, 99);
    await this.redis.expire(`webhook:log:${log.webhookId}`, 86400 * 30);
  }
}

Webhook Receiver with Signature Verification

// webhook-receiver.middleware.ts
import { Request, Response, NextFunction } from 'express';
import crypto from 'crypto';
import { Redis } from 'ioredis';

export class WebhookReceiver {
  private redis: Redis;

  constructor(redis: Redis) {
    this.redis = redis;
  }

  private verifySignature(payload: string, signature: string, secret: string): boolean {
    const expectedSignature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
  }

  createVerificationMiddleware(getSecret: (req: Request) => string) {
    return (req: Request, res: Response, next: NextFunction) => {
      const signature = req.headers['x-webhook-signature'] as string;
      if (!signature) return res.status(401).json({ error: 'Missing signature' });

      const payload = (req as any).rawBody || JSON.stringify(req.body);
      if (!this.verifySignature(payload, signature, getSecret(req))) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
      next();
    };
  }

  createIdempotencyMiddleware() {
    return async (req: Request, res: Response, next: NextFunction) => {
      const webhookId = req.headers['x-webhook-id'] as string;
      if (!webhookId) return res.status(400).json({ error: 'Missing webhook ID' });

      const key = `webhook:processed:${webhookId}`;
      if (await this.redis.exists(key)) {
        return res.status(200).json({ success: true, message: 'Already processed' });
      }

      await this.redis.setex(key, 86400, Date.now().toString());
      next();
    };
  }

  createTimestampValidationMiddleware(toleranceMs = 300000) {
    return (req: Request, res: Response, next: NextFunction) => {
      const timestamp = parseInt(req.headers['x-webhook-timestamp'] as string);
      if (!timestamp) return res.status(400).json({ error: 'Missing timestamp' });

      const diff = Math.abs(Date.now() - timestamp);
      if (diff > toleranceMs) {
        return res.status(400).json({ error: 'Timestamp too old', diff, tolerance: toleranceMs });
      }
      next();
    };
  }
}

Webhook Testing with ngrok

// webhook-tester.ts
import ngrok from 'ngrok';
import express from 'express';

export class WebhookTester {
  private app = express();
  private receivedWebhooks: any[] = [];

  constructor() {
    this.setupRoutes();
  }

  private setupRoutes() {
    this.app.use(express.json());

    this.app.post('/webhook/test', (req, res) => {
      this.receivedWebhooks.push({
        id: req.headers['x-webhook-id'],
        event: req.headers['x-webhook-event'],
        body: req.body,
        receivedAt: Date.now()
      });
      res.status(200).json({ success: true });
    });

    this.app.get('/webhook/received', (req, res) => {
      res.json({ count: this.receivedWebhooks.length, webhooks: this.receivedWebhooks });
    });
  }

  async start(port = 3000) {
    return new Promise((resolve, reject) => {
      this.app.listen(port, async () => {
        const url = await ngrok.connect({ addr: port, proto: 'http' });
        resolve({ localUrl: `http://localhost:${port}`, publicUrl: url });
      });
    });
  }

  async stop() {
    await ngrok.disconnect();
    await ngrok.kill();
  }
}

Best Practices

1. Always verify signatures - Use HMAC-SHA256
2. Implement idempotency - Prevent duplicate processing
3. Use exponential backoff - Retry with increasing delays
4. Validate timestamps - Prevent replay attacks (5-min window)
5. Return 2xx immediately - Process asynchronously
6. Log all deliveries - Track success/failures
7. Version payloads - Include version in schema
8. Test with ngrok - Local webhook testing
9. Set timeouts - 30s max for webhook delivery
10. Monitor health - Track delivery rates/latencies