Webhook

A webhook is an automated message sent from one application to another when a specific event occurs. Instead of constantly asking "did anything happen?", applications get notified immediately when something relevant occurs.

Analogy:

• Polling (API): Checking your mailbox every 5 minutes
• Webhook: Getting a doorbell ring when mail arrives

How it works:

1. You provide a URL endpoint to receive notifications
2. When an event happens, the source sends data to your URL
3. Your endpoint processes the incoming data
4. You take action based on the event

Example: When a customer completes a payment (Stripe), a webhook immediately notifies your app to:

• Update the order status
• Send confirmation email
• Trigger fulfillment

Webhooks enable real-time, event-driven architecture.

API (pull model):

• You request data when you want it
• You decide when to check
• Good for: On-demand data retrieval

Your app → Request → Server → Response → Your app

Webhook (push model):

• Server sends data when events happen
• Real-time notifications
• Good for: Event-driven updates

Event occurs → Server → Notification → Your endpoint

When to use each:

Most systems use both: webhooks for events, APIs for queries.

Receiving webhooks:

1. Create an endpoint:

app.post('/webhook', (req, res) => {
  const event = req.body;

  // Process the event
  handleEvent(event);

  // Acknowledge receipt quickly
  res.status(200).send('OK');
});

1. Verify authenticity:

const signature = req.headers['x-signature'];
const isValid = verifySignature(req.body, signature, secret);
if (!isValid) return res.status(401).send('Invalid');

1. Process asynchronously:

// Acknowledge immediately
res.status(200).send('OK');

// Process in background
queue.add('process-webhook', event);

Common patterns:

• Return 200 quickly (before processing)
• Verify signatures for security
• Handle duplicate events (idempotency)
• Log everything for debugging

Triggering AI workflows: Webhooks can start AI processes:

• New support ticket → AI generates draft response
• Form submission → AI analyzes and routes
• Document upload → AI processes and extracts data

AI agent callbacks: Long-running AI tasks use webhooks to report results:

• Start async AI task
• Get immediate acknowledgment
• Receive webhook when complete

Integration examples:

Customer support: Email received → Webhook → AI analyzes → Draft response → Agent reviews

Lead processing: Form submitted → Webhook → AI qualifies → CRM updated → Sales notified

Content moderation: User post → Webhook → AI reviews → Approve/flag → Notification sent

Chipp webhooks: Send conversation data to external systems for:

• CRM updates
• Analytics
• Custom workflows

Security:

• Always verify signatures
• Use HTTPS only
• Validate payload structure
• Implement IP allowlisting if possible

Reliability:

• Return 200 immediately, process async
• Implement retry handling
• Make handlers idempotent (safe to run twice)
• Log all incoming webhooks

Performance:

• Process heavy work in background queues
• Set timeouts on webhook handlers
• Monitor endpoint latency

Error handling:

• Handle malformed payloads gracefully
• Alert on repeated failures
• Implement dead letter queues

Testing:

• Use webhook testing tools (ngrok, webhook.site)
• Test with real and malformed payloads
• Verify retry behavior
• Check signature validation

Monitoring:

• Track success/failure rates
• Alert on unusual patterns
• Log processing times
• Monitor queue depths

Payments:

• Stripe: Payment events (charges, refunds, subscriptions)
• PayPal: Transaction notifications

Communication:

• Twilio: SMS/call events
• SendGrid: Email events (delivered, opened, clicked)
• Slack: Message events

Development:

• GitHub: Repository events (push, PR, issues)
• GitLab: CI/CD pipeline events

E-commerce:

• Shopify: Order and inventory events

CRM:

• Salesforce: Record changes
• HubSpot: Contact and deal events

AI/Automation:

• Zapier: Trigger automations
• Make: Workflow triggers

Most modern SaaS products offer webhooks for integration. When evaluating services, check their webhook documentation for reliability and features.