A webhook is an HTTP callback that delivers data from one application to another in real time when a specific event occurs. Instead of your application repeatedly asking a server "has anything changed?" (polling), the server pushes an HTTP POST request to a URL you provide the moment something happens. Payment confirmed, code pushed, invoice created, user signed up: the source system fires the webhook, and your system receives the data instantly.

Webhooks power the real-time connective tissue of modern software. Stripe uses them to notify you about payment outcomes. GitHub uses them to trigger CI/CD pipelines on every commit. Slack, Discord, Shopify, QuickBooks, and hundreds of other platforms rely on webhooks to keep systems synchronized without constant polling overhead.

This guide covers how webhooks work under the hood, how they compare to APIs and other communication patterns, real-world examples across major platforms, and practical guidance on security, reliability, and testing.

How webhooks work

The webhook lifecycle follows a straightforward sequence:

1. Registration. You provide a callback URL to the source application and specify which events you want to subscribe to. Some platforms offer a web UI for this; others expose an API for programmatic webhook management.
2. Event occurs. Something happens in the source system: a customer pays an invoice, a pull request is merged, a contact record is updated.
3. Payload delivery. The source system constructs an HTTP POST request containing event data (typically as a JSON body) and sends it to your registered URL.
4. Processing and acknowledgment. Your server receives the request, processes the data, and returns an HTTP 2xx status code to confirm receipt.
5. Retry on failure. If your server is unreachable or returns a non-success status code, most webhook providers will retry delivery using an exponential backoff schedule.

Here is an example webhook payload from the Discord webhook documentation:

{
  "name": "Create channel",
  "type": 1,
  "channel_id": "199737254929760256",
  "token": "3d89bb7572e0fb30d8128367b3b1b44fecd1726de135cbe28",
  "avatar": null,
  "guild_id": "199737254929760256",
  "id": "223704706495545344",
  "user": {
    "username": "darthvader",
    "discriminator": "7479",
    "id": "190320984123768832",
    "avatar": "b004ec1740a63ca06ae2e14c5cee11f3"
  }
}

The URL that receives the webhook acts as a listening endpoint. A typical webhook receiver URL might look like https://yourdomain.com/webhooks/stripe or https://yourdomain.com/api/v1/callbacks/github. The path structure is up to you, but the URL must be publicly accessible and capable of handling incoming POST requests.

Webhooks vs. REST APIs vs. WebSockets

Webhooks, REST APIs, and WebSockets each solve different communication problems. Understanding the tradeoffs helps you pick the right tool.

REST APIs follow a request-response model. Your application sends an HTTP request to a server, and the server returns data. The client initiates every interaction. If you want to know whether something has changed, you have to ask (poll) repeatedly. This works well for on-demand data retrieval but wastes resources when changes are infrequent.

Webhooks invert this model. The server pushes data to your application when an event occurs. You register a URL, and the source system calls it automatically. This is far more efficient for event-driven workflows because there is zero traffic when nothing has changed, and data arrives the moment something does.

WebSockets maintain a persistent, bidirectional connection between client and server. Both sides can send messages at any time without establishing new connections. WebSockets are ideal for low-latency, high-frequency communication like chat applications, live dashboards, or multiplayer games. But they require maintaining open connections, which adds infrastructure complexity.

The decision framework is simple. Use REST APIs when your application needs data on demand. Use webhooks when you need to react to events as they happen without polling. Use WebSockets when you need real-time, bidirectional, low-latency communication. In practice, most applications use all three: REST for CRUD operations, webhooks for event notifications, and WebSockets for live user-facing features.

Common webhook use cases

Webhooks show up in nearly every category of software:

• Payments and billing. Payment processors like Stripe and PayPal send webhook notifications for successful charges, failed payments, subscription renewals, disputes, and refunds. Your application receives immediate confirmation without polling.
• CI/CD and DevOps. GitHub, GitLab, and Bitbucket fire webhooks on pushes, pull requests, and merges. CI/CD platforms like Jenkins, CircleCI, and GitHub Actions use these to trigger automated builds, tests, and deployments.
• Chat and messaging. Slack, Discord, and Microsoft Teams use webhooks to deliver messages into channels. Development teams commonly route deployment notifications, error alerts, and monitoring updates into team channels through incoming webhooks.
• E-commerce. Shopify, WooCommerce, and BigCommerce send webhooks for new orders, inventory changes, and fulfillment updates. These drive real-time sync between storefronts and backend systems like ERPs and accounting software.
• Accounting and finance. QuickBooks, Xero, and other accounting platforms fire webhooks when invoices, payments, and journal entries are created or updated. This is the foundation of real-time accounting integration.
• CRM. Salesforce, HubSpot, and Pipedrive use webhooks to notify external systems when contacts, deals, or pipeline stages change.
• Authentication. Identity providers fire webhooks during login flows, password resets, and multi-factor authentication events.
• Cloud storage. Services like Google Drive, Dropbox, and Box send notifications when files are created, modified, or shared.

Consider a simple scenario: a user searches for a flight under $300 from New York to Singapore. No eligible flights exist right now, but the system saves their contact details and sends a webhook notification the moment a matching flight becomes available. The airline's backend fires the webhook, and the user receives an instant alert. No polling, no delays.

6 real-world webhook examples

Each platform implements webhooks with its own conventions. Here are six widely used webhook systems, updated for how they work today.

1. Stripe Webhooks

Stripe is the gold standard for webhook implementation. It uses webhooks extensively for payment lifecycle events: payment_intent.succeeded, invoice.paid, customer.subscription.deleted, charge.disputed, and dozens more. You configure webhook endpoints in the Stripe Dashboard or via the API, selecting exactly which event types to receive. Stripe signs every webhook payload with a Stripe-Signature header using HMAC-SHA256, allowing your server to verify authenticity. The Stripe CLI lets you forward webhook events to your local development server for testing, and Stripe provides a "Send test webhook" button in the Dashboard for manual verification.

2. GitHub Webhooks

GitHub webhooks can subscribe to over 40 event types at the repository or organization level: push, pull_request, issues, release, deployment, star, and more. When an event fires, GitHub sends a JSON payload to your registered URL with a X-Hub-Signature-256 header for HMAC verification. GitHub provides three webhook APIs for programmatic management: Repository Webhooks, Organization Webhooks, and GitHub App Webhooks. The most common use case is triggering CI/CD pipelines: a push to main fires a webhook that kicks off build, test, and deployment workflows.

3. Slack Webhooks and Events API

Slack offers incoming webhooks for posting messages to channels, which is the simplest way to send automated notifications into Slack. For receiving events from Slack (messages posted, reactions added, channels created), Slack's Events API is the current recommended approach, replacing the older outgoing webhooks. The Events API delivers events to your server's request URL with request signing for verification. Slack Apps, built through the Slack Platform, provide the most complete integration path, combining webhooks, interactive components, slash commands, and workflows.

4. Discord Webhooks

Discord provides webhooks for posting automated messages to channels. You create a webhook URL directly from Discord's server settings under Integrations, then point external services at that URL. Development teams commonly send GitHub commit notifications, monitoring alerts from Datadog or PagerDuty, and deployment status updates into Discord channels. Discord also offers an API to create, modify, and delete webhooks programmatically through HTTP requests.

5. Shopify Webhooks

Shopify webhooks notify your application about events in a merchant's store: orders/create, products/update, customers/create, inventory_levels/update, and many more. Shopify supports both HTTP and Amazon EventBridge as delivery methods. Each webhook payload is signed with an HMAC-SHA256 hash using the app's shared secret, sent in the X-Shopify-Hmac-SHA256 header. Shopify enforces mandatory compliance webhooks for apps distributed through the Shopify App Store, including customers/data_request, customers/redact, and shop/redact. This ensures apps respond to GDPR and privacy obligations automatically.

6. QuickBooks Webhooks

QuickBooks Online sends webhook notifications when entities like invoices, payments, customers, and bills are created, updated, or deleted. You configure a single webhook endpoint that receives notifications for all entity types you subscribe to. QuickBooks signs payloads using HMAC-SHA256 with a verifier token. A key implementation detail: QuickBooks webhook payloads contain only entity references (IDs and operation types), not full entity data. Your application must make a follow-up API call to retrieve the actual record. This pattern keeps webhook payloads small and avoids delivering stale data. For platforms building accounting integrations, QuickBooks webhooks are essential for real-time sync.

Webhook security best practices

Webhooks receive data from external servers, which makes security non-negotiable. Without proper verification, an attacker could send forged payloads to your webhook endpoint and trigger unintended actions in your system.

HMAC signature verification is the most widely adopted security mechanism. The webhook provider computes a hash of the payload using a shared secret and includes it in a request header. Your server recalculates the hash using the same secret and compares the result. If they match, the payload is authentic. Stripe uses Stripe-Signature, GitHub uses X-Hub-Signature-256, Shopify uses X-Shopify-Hmac-SHA256, and Apideck uses X-Apideck-Signature. Always use timing-safe comparison functions to prevent timing attacks.

Mutual TLS (mTLS) provides certificate-based authentication where both client and server verify each other's identity before data is exchanged. This is common in enterprise and financial services integrations where regulatory requirements demand stronger authentication than shared secrets alone.

IP allowlisting restricts which IP addresses can send requests to your webhook endpoint. Many providers publish their IP ranges (for example, GitHub's meta API endpoint includes webhook IP ranges). This adds a layer of defense but should not be your only security measure, since IP addresses can be spoofed.

Timestamp validation prevents replay attacks. Many providers include a timestamp in the webhook header or payload. Your server should reject any webhook where the timestamp is too far in the past (typically more than 5 minutes). Stripe combines timestamp and signature into a single verification step.

HTTPS only. Always use HTTPS for your webhook URLs. This encrypts data in transit and prevents man-in-the-middle interception. Most webhook providers require HTTPS endpoints for production use.

Webhook reliability: retries, idempotency, and ordering

Webhooks are delivered over HTTP, which means they can fail. Networks go down, servers restart, deployments cause brief outages. Building reliable webhook consumers requires handling three challenges: failed deliveries, duplicate deliveries, and out-of-order deliveries.

Retry policies. Most providers automatically retry failed webhook deliveries using exponential backoff. Stripe retries up to 3 days. GitHub retries for up to 3 days as well, marking the webhook as failed if all attempts are exhausted. Shopify retries 19 times over 48 hours. Your server should return a 2xx status code quickly (within a few seconds) to acknowledge receipt, then process the payload asynchronously. If your endpoint takes too long to respond, the provider may time out and retry, leading to duplicate deliveries.

Idempotency. Because retries can deliver the same event multiple times, your webhook handler must be idempotent: processing the same event twice should produce the same result as processing it once. The standard approach is to store the event ID from the webhook payload and check for duplicates before processing. Stripe includes an id field in every event; GitHub includes a X-GitHub-Delivery header with a unique GUID.

Event ordering. Webhooks can arrive out of order, especially during retries. A customer.updated event might arrive before customer.created if the creation webhook initially failed and was retried. Design your handlers to be order-independent where possible, or use timestamps and sequence numbers to enforce ordering when business logic requires it.

Dead letter queues. For critical integrations, route persistently failing webhooks to a dead letter queue for manual review. This ensures you never silently lose events, even when your handler has a bug or an upstream format changes unexpectedly.

Testing webhooks

Testing webhooks requires simulating the behavior of an external system pushing data to your endpoint. Several approaches work well.

Local development tools. The Stripe CLI can forward live or test webhook events to your local machine. ngrok creates a public tunnel to your localhost, giving you a temporary URL that external services can reach. This is invaluable during development because webhook providers cannot reach localhost directly.

Webhook inspection tools. Webhook.site and RequestBin provide disposable URLs that capture incoming HTTP requests, letting you inspect headers, payloads, and status codes without writing any server-side code. These are useful for verifying that a webhook is configured correctly before building your handler.

Manual testing with HTTP clients. Since webhooks are just HTTP POST requests, you can simulate them using curl, Postman, or any HTTP client. Construct a JSON payload matching the provider's format and POST it to your endpoint:

curl -X POST https://yourdomain.com/webhooks/test \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.completed", "data": {"amount": 4999, "currency": "usd"}}'

A successful webhook should return a 2xx HTTP status code. A 4xx or 5xx indicates something went wrong on your end.

Provider-specific test modes. Stripe offers a "Send test webhook" button in the Dashboard. GitHub lets you redeliver any past webhook from the repository settings page. Shopify provides a webhook testing tool in the Partner Dashboard. Use these to validate your integration against realistic payloads.

API-based webhook management

Beyond configuring webhooks through a UI, many platforms offer APIs for managing webhook subscriptions programmatically. This is essential for SaaS applications that need to register, update, and delete webhooks on behalf of their users at scale.

HubSpot, for example, provides a Webhooks API to configure subscriptions programmatically. You can create event subscriptions, adjust concurrency settings, and manage endpoint URLs through API calls rather than clicking through a dashboard.

Shopify's webhook API lets apps register for specific topics (orders/create, products/update) and manage subscriptions using GraphQL or REST. This is how most Shopify apps handle real-time data sync.

For platforms that need to manage webhooks across many different integrations simultaneously, Apideck's webhook infrastructure provides a unified approach. Rather than implementing separate webhook subscription logic for every integration (Stripe's webhook API is different from QuickBooks' is different from Xero's), a unified API normalizes webhook events across 200+ connectors into a single, consistent format. For integrations that don't natively support webhooks, Apideck provides virtualized webhooks that poll the underlying API and emit webhook-style events, so your application gets a consistent event-driven interface regardless of the downstream system's capabilities.

Webhooks in API specifications: OpenAPI, AsyncAPI, and CloudEvents

The API ecosystem has increasingly formalized how webhooks are defined, documented, and consumed.

OpenAPI has supported callbacks (provider-initiated HTTP requests) for several versions. Starting with OpenAPI v3.1, the specification introduced a dedicated top-level webhooks element for describing webhooks that are registered and managed out of band. This means API providers can now document their webhook payloads with the same rigor they apply to their request-response endpoints, including schema validation, security definitions, and example payloads.

AsyncAPI is specifically designed for event-driven architectures. While OpenAPI describes synchronous request-response APIs, AsyncAPI defines asynchronous communication patterns including AMQP, MQTT, Kafka, STOMP, WebSocket, and HTTP webhooks. If you're building a platform that both sends and receives events across multiple protocols, AsyncAPI provides the most complete specification.

CloudEvents is a CNCF specification that defines a standard envelope format for event data. Rather than every provider inventing its own payload structure, CloudEvents provides common attributes (source, type, id, time, data) that make events portable across systems. Adoption is growing across cloud providers and event-driven platforms.

For teams designing APIs in the agentic era, webhook specifications matter even more. AI agents need machine-readable webhook schemas to understand what events a system can fire and what data those events contain. Well-documented webhook schemas in OpenAPI or AsyncAPI format allow agents to autonomously subscribe to relevant events and process incoming data without human intervention.

Webhooks for integration platforms

If you're building a SaaS product that integrates with multiple external platforms, webhooks quickly become a scaling challenge. Each integration has its own webhook format, security mechanism, retry policy, and subscription management API. Supporting webhooks from Stripe plus QuickBooks plus Salesforce plus Shopify means four separate implementations, each with its own authentication, payload parsing, and error handling logic.

This is exactly the problem that unified APIs solve. Instead of building custom webhook handlers for every integration, a unified API normalizes events from all connected platforms into a consistent webhook format. Your application registers one webhook endpoint and receives standardized events regardless of whether the source is QuickBooks, Xero, NetSuite, Sage, or any other connected system.

Apideck's webhook infrastructure handles this normalization at the platform level. Native webhooks from integrations that support them (like QuickBooks and Xero) are translated into a unified event format. For integrations that lack native webhook support, virtualized webhooks poll the underlying API on a schedule and emit events when changes are detected. The result: your application gets a single, reliable event stream across every integration without building polling infrastructure or maintaining dozens of separate webhook handlers.

FAQ

What is the difference between a webhook and an API?

A REST API follows a request-response model: your application asks for data, and the server responds. A webhook is event-driven: the server pushes data to your application automatically when something happens. APIs require your application to initiate the conversation; webhooks let the server start it. Most modern systems use both: APIs for on-demand data access and webhooks for real-time event notifications.

Are webhooks secure?

Webhooks are as secure as you make them. Best practices include verifying HMAC signatures on every incoming payload, requiring HTTPS endpoints, validating timestamps to prevent replay attacks, and optionally implementing IP allowlisting. Most major providers (Stripe, GitHub, Shopify, Apideck) include cryptographic signatures with every webhook delivery.

What happens if my webhook endpoint is down?

Most webhook providers implement automatic retry logic with exponential backoff. If your server is temporarily unavailable, the provider will retry delivery over a period ranging from hours to days depending on the platform. Your webhook handler should be idempotent (safe to process the same event more than once) to handle retries gracefully.

Can I test webhooks locally?

Yes. Tools like the Stripe CLI, ngrok, and localtunnel create tunnels that expose your local development server to the internet, allowing webhook providers to deliver payloads to your machine. You can also use Webhook.site or RequestBin to inspect payloads without running any server code.

What format do webhook payloads use?

The vast majority of modern webhook providers send JSON payloads via HTTP POST. Some older systems use XML or form-encoded data. The payload structure varies by provider but typically includes an event type, a timestamp, and the event data itself.

How are webhooks different from WebSockets?

Webhooks are one-directional (server to your endpoint) and stateless: each delivery is an independent HTTP request. WebSockets maintain a persistent, bidirectional connection between client and server. Webhooks are better for event notifications between backend systems. WebSockets are better for real-time user-facing features like chat, live dashboards, or multiplayer interactions.

Final thoughts

Webhooks are the backbone of real-time, event-driven software architecture. They eliminate wasteful polling, enable instant data synchronization, and provide the foundation for automated workflows across every category of software.

The key to getting webhooks right: verify every payload with HMAC signatures, build idempotent handlers that survive retries and duplicates, return 2xx responses quickly and process asynchronously, and use structured logging to debug delivery issues. If you're managing webhooks across multiple integrations, a unified API approach can dramatically reduce the engineering overhead of handling different webhook formats, security mechanisms, and subscription APIs across dozens of platforms.

According to a survey conducted by Zapier, 82% of developers preferred webhooks over polling. As software architectures continue shifting toward event-driven patterns and AI agents that need to react to real-time changes, webhooks will only become more central to how systems communicate.