Documentation

Complete guide to webhooks, debugging, and real-time event monitoring with HookMetry

What are Webhooks?

A webhook is an HTTP callback that sends real-time data from one application to another when a specific event occurs. Think of it as a "reverse API" - instead of you requesting data, the service proactively pushes data to you automatically when something happens.

Simple Analogy

Traditional API (Polling)

Like constantly checking your mailbox every 5 minutes to see if mail arrived

Wastes resources, delays notifications

✅ Webhook (Event-Driven)

Like a doorbell that rings when mail is delivered

Efficient, instant, real-time

How Webhooks Work

  1. 1Event Occurs: Something happens in a service (e.g., payment completed, user signed up, PR merged)
  2. 2HTTP POST Request: Service sends a POST request to your webhook URL with event data
  3. 3Your Server Receives: Your application receives and processes the webhook payload
  4. 4Response Sent: Your server responds with HTTP 200 to acknowledge receipt

Webhooks vs REST APIs

AspectWebhooks (Push)REST APIs (Pull)
CommunicationServer pushes data to youYou request data from server
TimingReal-time (instant)On-demand or polling
EfficiencyHigh (event-driven)Low (repeated requests)
Resource UsageMinimal (only when needed)Wasteful (constant polling)
Setup ComplexityRequires public endpointSimple client-side requests
Use CaseNotifications, events, updatesData retrieval, queries
Example"Payment completed" alert"Get user profile" request

Real-World Use Cases

Payment Processing (Stripe, PayPal)

When a customer completes a payment, webhook instantly notifies your server to:

  • • Update order status in database
  • • Send confirmation email to customer
  • • Grant access to purchased content
  • • Trigger fulfillment process

CI/CD Pipelines (GitHub, GitLab, CircleCI)

When code is pushed or PR is merged, webhook triggers:

  • • Automated test suite execution
  • • Build and deployment processes
  • • Code quality checks and linting
  • • Slack notifications to team

E-commerce & Inventory (Shopify, WooCommerce)

When order is placed or inventory changes, webhook enables:

  • • Real-time inventory sync across platforms
  • • Automated shipping label generation
  • • Customer order tracking updates
  • • Low stock alerts to suppliers

Chat & Communication (Slack, Discord, Teams)

When messages or events occur, webhook powers:

  • • Bot commands and automated responses
  • • Cross-platform message synchronization
  • • Alert notifications for critical events
  • • Custom workflow automations

SaaS Integrations (Zapier, Make, n8n)

Connect different apps without code:

  • • "New email Save to Google Sheets"
  • • "Form submission Create CRM contact"
  • • "Calendar event Send SMS reminder"
  • • "New subscriber Add to mailing list"

Analytics & Monitoring (DataDog, Sentry)

Get instant alerts when issues occur:

  • • Error notifications to Slack/PagerDuty
  • • Performance degradation warnings
  • • Security incident alerts
  • • User behavior anomaly detection

Why Use Webhooks?

  • ✅ Real-time: Instant notifications (milliseconds)
  • ✅ Efficient: No polling = lower server costs
  • ✅ Scalable: Handles millions of events
  • ✅ Reliable: Automatic retries on failure
  • ✅ Event-Driven: Modern architecture pattern
  • ✅ Battery-Friendly: Saves mobile device resources

Webhook Challenges

  • Debugging: Hard to test locally (Hookmetry solves this!)
  • Security: Must validate signatures
  • Delivery: Network issues can cause failures
  • Ordering: Events may arrive out of sequence
  • Duplicates: Same event may be sent twice
  • Endpoint Visibility: Requires public URL

When to Use Webhooks vs Polling

✅ Use Webhooks When:

  • • Events happen infrequently (payments, signups)
  • • Real-time notifications are critical
  • • You want to reduce server load and costs
  • • The event source supports webhooks
  • • You have a publicly accessible endpoint

Use Polling (REST API) When:

  • • You need to control request timing
  • • Webhooks are not supported by the service
  • • Running behind a firewall (no public URL)
  • • You need to query historical data
  • • Events are very frequent (better to batch)

Complete Example: Stripe Payment Flow

1. Customer completes payment Stripe processes transaction

2. Stripe sends webhook POST request to your endpoint with payment data

3. Your server receives webhook Validates signature, processes event

4. Your app takes action Updates database, sends email, grants access

5. Response sent HTTP 200 confirms receipt to Stripe

All of this happens in under 1 second - completely automated!

🚀 Why Hookmetry Exists

Webhooks are powerful but notoriously difficult to debug. You can't easily test them on localhost, signature validation is complex, and production issues are hard to reproduce. Hookmetry gives you a public endpoint to capture webhooks, inspect every detail, validate signatures, and replay them to your development server - making webhook development as easy as testing a regular API.