Webhooks: Real-Time Automation for OpenClaw

A webhook is like a doorbell. Without one, you would have to open your front door every few minutes to see if someone is there — an exhausting and wasteful routine called polling. With a doorbell, you get notified instantly when someone arrives. Webhooks are the doorbell of the internet.

Instead of repeatedly asking external services "any updates?" — a practice that wastes API calls, compute resources, and patience — webhooks flip the conversation. When something happens, the service tells you. This shift from pull to push is the foundation of modern real-time automation.

How webhooks work

At its core, a webhook is an HTTP POST request sent from one server to another when a specific event occurs. Here is the flow:

1. You register a URL endpoint with a service ("send webhooks here when X happens")
2. An event occurs in that service (payment received, code pushed, form submitted)
3. The service sends an HTTP POST to your endpoint with event data
4. Your application receives, validates, and processes the payload
5. You return a 2xx status code to acknowledge receipt

The payload is typically JSON containing details about the event: what happened, when it occurred, and relevant data like user IDs, amounts, or object states.

Webhooks vs polling: The cost of asking

A SaaS company was polling their payment provider's API every 30 seconds to check for new transactions. At 100,000 users, those 2.8 million daily requests cost them $50,000 per year in API fees and compute resources. The updates still arrived an average of 15 seconds late. Switching to webhooks cut costs by 98% and delivered notifications in milliseconds.

This story repeats across industries. Polling is the ultimate waste: asking the same question thousands of times when the answer is usually "nothing changed." The Japanese concept of mottainai — regret over waste — captures the sentiment perfectly. Webhooks embody a better principle: only speak when you have something to say.

When to use polling instead

Webhooks are not always the answer. Use polling when:

• The service does not support webhooks
• You need data on a predictable schedule regardless of events
• Your endpoint cannot be exposed to the public internet
• You require strict control over when processing occurs
• The event volume is so low that polling is actually cheaper

Common webhook use cases

IFTTT (If This Then That) launched in 2010 with a simple premise: when one service triggers an event, notify another. Their entire architecture was webhook-driven. By 2021, they processed 1 billion applets monthly — all triggered by webhooks. The lesson: webhooks do not just connect services; they enable entire ecosystems.

Payment processing

Stripe, PayPal, and other payment providers use webhooks to notify your application when payments succeed, fail, or dispute. This enables instant order fulfillment, failed payment recovery flows, and fraud detection without polling payment statuses.

Code repository events

GitHub, GitLab, and Bitbucket send webhooks for pushes, pull requests, issues, and releases. This triggers CI/CD pipelines, updates project management tools, notifies team chat channels, and deploys code automatically.

Form submissions and leads

Typeform, Google Forms, and lead capture tools send webhooks when someone submits. This enables instant CRM updates, email sequences, Slack notifications, and sales team alerts — no more waiting for batch syncs.

E-commerce automation

Shopify, WooCommerce, and BigCommerce send webhooks for orders, inventory changes, and customer updates. This powers real-time inventory sync, order fulfillment workflows, and customer service alerts.

IoT and sensors

Connected devices use webhooks to report sensor data, status changes, and alerts. Temperature thresholds exceeded, motion detected, machinery failures — all can trigger immediate responses via webhooks.

Setting up webhooks in OpenClaw

OpenClaw can receive webhooks through its gateway and process them with your agent. Here is how to configure them:

1. Expose your OpenClaw instance

Webhooks require a public URL that external services can reach. Options include:

• Cloud deployment: Your instance already has a public IP/domain
• Tailscale: Use Tailscale's funnel feature to expose a public endpoint
• ngrok: Create a tunnel for local development (not for production)
• Reverse proxy: Configure nginx or similar with SSL termination

2. Configure the webhook endpoint

In your OpenClaw configuration, define webhook routes:

webhooks:
  enabled: true
  endpoints:
    stripe:
      path: /webhooks/stripe
      secret: ${STRIPE_WEBHOOK_SECRET}
      handler: agents.stripe_handler
    github:
      path: /webhooks/github
      secret: ${GITHUB_WEBHOOK_SECRET}
      handler: agents.github_handler

3. Register with the external service

In Stripe, GitHub, or your service of choice, add your webhook URL and select the events you want to receive. The service will send a test ping to verify connectivity.

4. Create your handler agent

Build an OpenClaw agent that processes webhook payloads:

# AGENTS.md
agents:
  stripe_handler:
    description: Process Stripe webhook events
    instructions: |
      You receive Stripe webhook events. Validate the signature,
      extract the event data, and take appropriate action:
      
      - payment_intent.succeeded: Fulfill order, send confirmation
      - payment_intent.payment_failed: Notify customer, log for review
      - charge.dispute.created: Alert support team, freeze payouts
      
      Always verify the webhook signature before processing.

Webhook security essentials

Webhook security is like a secret knock. Anyone can knock on your door, but only someone who knows the specific pattern gets let in. Signature verification is that pattern — it proves the webhook actually came from the service you trust, not an impostor.

Signature verification

Always verify webhook signatures using the provider's secret key. Never process a webhook without validation. Here is the general pattern:

1. Extract the signature from webhook headers (usually X-Signature or similar)
2. Compute an HMAC of the raw payload using your webhook secret
3. Compare the computed signature with the received signature
4. Only process if they match exactly

HTTPS only

Never accept webhooks over HTTP. Always use HTTPS with valid SSL certificates. This prevents man-in-the-middle attacks that could steal or modify webhook payloads.

Idempotency keys

Webhooks can be delivered multiple times due to retries. Include idempotency checks to prevent duplicate processing. Most providers include an event ID you can use to track processed webhooks.

Payload validation

Validate the structure and content of webhook payloads before processing. Reject unexpected fields, validate required data, and sanitize inputs to prevent injection attacks.

IP allowlisting

When possible, restrict webhook endpoints to accept requests only from known provider IP ranges. Services like Stripe and GitHub publish their IP ranges for this purpose.

Handling webhook failures

Webhooks fail. Networks glitch, servers restart, code has bugs. A robust webhook implementation handles failures gracefully:

Return 2xx quickly

Acknowledge receipt with a 200 status immediately, then process asynchronously. Webhook providers have timeouts (often 5-30 seconds). If you timeout, they will retry — potentially causing duplicate processing.

Implement retries with backoff

When calling downstream services from your webhook handler, implement your own retry logic with exponential backoff. Do not let a temporary failure cascade.

Use a queue

For high-volume or critical webhooks, place incoming events in a message queue (RabbitMQ, AWS SQS, Redis) before processing. This decouples receipt from processing and provides buffering during traffic spikes.

Monitor and alert

Track webhook delivery rates, processing times, and error rates. Alert when failure rates spike or latency increases. Many providers offer webhook delivery logs in their dashboards.

Testing webhooks locally

Developing with webhooks locally requires exposing your machine to the internet. Here are the best approaches:

ngrok for development

ngrok creates a secure tunnel to your localhost with a public URL:

ngrok http 8080

Use the generated HTTPS URL as your webhook endpoint. ngrok also provides a web interface to inspect incoming requests and replay webhooks for testing.

Webhook.site for inspection

Webhook.site generates a unique URL that captures and displays incoming webhooks. Use it to inspect payload structure before building your handler.

Provider test events

Most services let you send test webhooks from their dashboard. Use these to verify your endpoint responds correctly without triggering real events.

Webhook best practices summary

• Verify signatures on every webhook — never trust unverified payloads
• Use HTTPS with valid certificates for all webhook endpoints
• Return 2xx immediately and process asynchronously to avoid timeouts
• Implement idempotency to handle duplicate deliveries gracefully
• Validate payloads before processing to prevent injection attacks
• Use queues for buffering and decoupling in high-volume scenarios
• Monitor delivery and alert on failures or unusual patterns
• Document your endpoints with expected payload formats and retry behavior

Webhooks transform applications from passive tools waiting to be asked into active systems that respond instantly to the world. Master them, and you unlock real-time automation that feels almost magical.