Webhook Automation

SKILL.md

Webhook Automation

Comprehensive skill for building webhook-based integrations and real-time event processing.

Core Concepts

Webhook Architecture
WEBHOOK FLOW:
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Source    │────▶│   Webhook   │────▶│   Handler   │
│   System    │     │   Endpoint  │     │   Logic     │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼───────┐
                    │                          │       │
                    ▼                          ▼       ▼
              ┌──────────┐              ┌──────────┐ ┌──────────┐
              │  Action  │              │  Action  │ │  Action  │
              │    A     │              │    B     │ │    C     │
              └──────────┘              └──────────┘ └──────────┘

Webhook Types

webhook_types:
  incoming:
    description: "Receive events from external services"
    use_cases:
      - Payment notifications (Stripe, PayPal)
      - Form submissions
      - CRM updates
      - CI/CD events
      
  outgoing:
    description: "Send events to external services"
    use_cases:
      - Notify external systems
      - Trigger workflows
      - Sync data
      - Alert integrations

Webhook Endpoint Setup

Basic Endpoint

webhook_endpoint:
  url: "https://api.example.com/webhooks/incoming"
  method: POST
  
  authentication:
    type: signature
    header: "X-Signature-256"
    algorithm: "HMAC-SHA256"
    secret: "${WEBHOOK_SECRET}"
    
  validation:
    required_headers:
      - "Content-Type"
      - "X-Request-ID"
    content_types:
      - "application/json"
      - "application/x-www-form-urlencoded"
      
  response:
    success:
      status: 200
      body: { "received": true }
    error:
      status: 400
      body: { "error": "Invalid payload" }

Signature Verification

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

// Usage
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature-256'];
  const payload = JSON.stringify(req.body);
  
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook...
  processWebhook(req.body);
  res.status(200).json({ received: true });
});

Event Processing

Event Router

event_router:
  routes:
    - event_type: "payment.succeeded"
      handler: processPayment
      actions:
        - update_order_status
        - send_confirmation_email
        - notify_fulfillment
        
    - event_type: "customer.created"
      handler: processNewCustomer
      actions:
        - create_crm_contact
        - send_welcome_email
        - assign_to_sales
        
    - event_type: "subscription.cancelled"
      handler: processChurn
      actions:
        - update_subscription_status
        - trigger_retention_flow
        - notify_customer_success
        
    - event_type: "*"
      handler: logUnhandled
      actions:
        - log_to_monitoring

Payload Transformation

transformations:
  - name: stripe_to_internal
    source: stripe_webhook
    target: internal_order
    mapping:
      id: "data.object.id"
      amount: "data.object.amount / 100"  # Cents to dollars
      currency: "data.object.currency | uppercase"
      customer_email: "data.object.receipt_email"
      created_at: "data.object.created | timestamp"
      metadata: "data.object.metadata"
      
  - name: github_to_slack
    source: github_webhook
    target: slack_message
    mapping:
      text: |
        *{{action | capitalize}} {{repository.name}}*
        {{#if pull_request}}
        PR: {{pull_request.title}}
        By: {{pull_request.user.login}}
        {{/if}}
      channel: "{{repository.name}}-notifications"

Common Integrations

Stripe Webhooks

stripe_webhooks:
  endpoint_secret: "${STRIPE_WEBHOOK_SECRET}"
  
  events:
    - type: "checkout.session.completed"
      handler: |
        async function(event) {
          const session = event.data.object;
          await fulfillOrder(session);
          await sendReceipt(session.customer_email);
        }
        
    - type: "invoice.payment_failed"
      handler: |
        async function(event) {
          const invoice = event.data.object;
          await notifyCustomer(invoice);
          await createDunningTask(invoice);
        }
        
    - type: "customer.subscription.updated"
      handler: |
        async function(event) {
          const subscription = event.data.object;
          await syncSubscriptionStatus(subscription);
        }

GitHub Webhooks

github_webhooks:
  secret: "${GITHUB_WEBHOOK_SECRET}"
  
  events:
    - type: "push"
      branches: ["main", "develop"]
      handler: |
        async function(event) {
          await triggerCI(event.repository, event.ref);
          await notifyTeam(event.commits);
        }
        
    - type: "pull_request"
      actions: ["opened", "synchronize"]
      handler: |
        async function(event) {
          await runTests(event.pull_request);
          await requestReview(event.pull_request);
        }
        
    - type: "issues"
      actions: ["opened"]
      handler: |
        async function(event) {
          await triageIssue(event.issue);
          await assignOwner(event.issue);
        }

Slack Webhooks

slack_webhooks:
  incoming:
    # Receive slash commands and interactions
    signing_secret: "${SLACK_SIGNING_SECRET}"
    
    events:
      - type: "slash_command"
        command: "/deploy"
        handler: handleDeployCommand
        
      - type: "interactive_message"
        callback_id: "approval_*"
        handler: handleApproval
        
  outgoing:
    # Send messages to Slack
    webhook_url: "${SLACK_WEBHOOK_URL}"
    
    templates:
      alert:
        blocks:
          - type: section
            text: "🚨 *Alert:* {{message}}"
          - type: context
            elements:
              - type: mrkdwn
                text: "Source: {{source}} | Time: {{timestamp}}"

Error Handling

Retry Strategy

retry_config:
  enabled: true
  
  policy:
    max_attempts: 5
    initial_delay: 1000  # ms
    max_delay: 60000  # ms
    backoff_multiplier: 2
    
  retry_on:
    status_codes: [408, 429, 500, 502, 503, 504]
    exceptions: ["ECONNRESET", "ETIMEDOUT"]
    
  dead_letter:
    enabled: true
    destination: "failed_webhooks_queue"
    retention_days: 7

Error Logging

error_handling:
  logging:
    level: error
    include:
      - request_id
      - event_type
      - payload_hash
      - error_message
      - stack_trace
      - retry_count
      
  alerting:
    on_failure:
      - type: slack
        channel: "#webhook-alerts"
        threshold: 5  # failures per minute
        
    on_dead_letter:
      - type: pagerduty
        severity: warning

Webhook Testing

Test Payload Generator

test_payloads:
  stripe_payment:
    type: "checkout.session.completed"
    data:
      object:
        id: "cs_test_123"
        amount_total: 2000
        currency: "usd"
        customer_email: "test@example.com"
        payment_status: "paid"
        
  github_push:
    ref: "refs/heads/main"
    repository:
      name: "my-repo"
      full_name: "org/my-repo"
    commits:
      - id: "abc123"
        message: "Test commit"
        author:
          name: "Test User"

Webhook Debugging

debugging:
  tools:
    - name: "Request Bin"
      url: "https://requestbin.com"
      use: "Capture and inspect payloads"
      
    - name: "ngrok"
      command: "ngrok http 3000"
      use: "Expose local server"
      
    - name: "Webhook.site"
      url: "https://webhook.site"
      use: "Quick webhook testing"
      
  logging:
    enabled: true
    log_payloads: true
    log_headers: true
    mask_secrets: true

Security Best Practices

Security Checklist

security:
  authentication:
    - Verify webhook signatures
    - Use HTTPS only
    - Rotate secrets regularly
    
  validation:
    - Validate payload schema
    - Check timestamp freshness
    - Verify source IP if possible
    
  processing:
    - Idempotent handlers
    - Rate limiting
    - Timeout protection
    
  storage:
    - Encrypt secrets at rest
    - Audit logging
    - No sensitive data in URLs

IP Allowlisting

ip_allowlist:
  stripe:
    - "3.18.12.63"
    - "3.130.192.231"
    # ... more IPs
    
  github:
    - "192.30.252.0/22"
    - "185.199.108.0/22"
    # ... more ranges
    
  slack:
    - "54.159.240.0/22"
    # ... more ranges

Monitoring

Metrics Dashboard

WEBHOOK METRICS - LAST 24 HOURS
═══════════════════════════════════════

Received:      12,456
Processed:     12,398 (99.5%)
Failed:           58 (0.5%)
Retried:         123

BY SOURCE:
Stripe     ████████████░░░░ 5,230
GitHub     ██████████░░░░░░ 4,120
Slack      ████░░░░░░░░░░░░ 1,850
Other      ███░░░░░░░░░░░░░ 1,256

LATENCY (p99):
Processing: 245ms
Response:   52ms

ERROR BREAKDOWN:
Timeout:       25
Invalid Sig:   18
Parse Error:   10
Rate Limited:   5

Best Practices

Respond Quickly: Return 200 immediately, process async

Idempotency: Handle duplicate events gracefully

Verify Signatures: Always validate webhook authenticity

Log Everything: Maintain audit trail

Retry Logic: Implement exponential backoff

Dead Letters: Don't lose failed events

Rate Limiting: Protect against flood attacks

Monitoring: Alert on failures and latency