om-scogo 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