What Is a Webhook and How Does It Work

You're refreshing a payment page, waiting for a video export to finish, or checking whether a social post has finally published. The application knows something changed, but your system doesn't, so it keeps asking the same question: “Is it ready yet?” That repeated checking is polling. A webhook replaces that pattern with a notification sent at the moment the event happens.

So, what is a webhook and how does it work? A webhook is an event-driven HTTP callback. You register a URL with a provider, select the events you care about, and the provider sends an HTTP POST containing event data when one of those events occurs. Your server verifies the request, accepts it, and starts the appropriate action.

The basic idea is simple. Production reliability isn't. Duplicate deliveries, retries, replay attacks, slow handlers, and changing payloads all matter once a webhook controls payments, fulfillment, publishing, or customer workflows.

Table of Contents

• The Core Concept Behind Event-Driven Callbacks
  • Push instead of repeated questions
  • Why the pattern remains useful
• Anatomy of an HTTP POST Payload
  • What the provider sends
  • What the receiver does
• Webhooks vs Polling vs Message Queues
  • Integration pattern comparison
• Designing for At-Least-Once Delivery
  • Make repeated delivery harmless
  • Keep the edge fast
• Securing Endpoints Against Replay Attacks
  • Verify the exact request
  • Make old requests unusable
• Real-World Automation and Social Publishing
  • Where the abstraction helps
• Testing and Debugging Local Endpoints
  • A practical debugging loop

The Core Concept Behind Event-Driven Callbacks

Suppose a customer completes checkout. A polling-based integration might ask the payment service repeatedly whether the payment has cleared. Most requests return the same answer, nothing has changed, while the application spends resources checking.

A webhook reverses who starts the conversation. The payment service detects the completed payment and sends a notification to your registered endpoint. Your system can then release an order, update a dashboard, or start a fulfillment workflow without refreshing a page or scheduling another request.

Practical rule: Poll when you need to retrieve state on demand. Use a webhook when you need to react to a state change.

Jeff Lindsay coined the term webhook in 2007, describing a way for one web application to notify another when an event occurs instead of requiring repeated polling. That origin marks an important shift from request-heavy integration patterns toward event-driven HTTP callbacks. The approach became a practical foundation for SaaS integrations because it combines a simple web protocol with near real-time automation. (The history and mechanics of webhooks)

Push instead of repeated questions

A webhook has three essential parts:

• A triggering event: A payment clears, a record changes, or a video finishes processing.
• A callback URL: Your application gives the provider an endpoint that can receive the notification.
• An acknowledgment: Your endpoint returns an HTTP 2xx response to confirm that it received the delivery.

The provider usually sends an HTTP POST with a JSON body. The receiver validates the request, reads the event, and either processes it immediately or places it into a durable queue for asynchronous work. If the endpoint returns a non-2xx status, times out, or cannot be reached, many implementations retry the delivery. (Technical webhook lifecycle details)

That makes a webhook different from a generic API call. With a normal API request, your application initiates the interaction and asks for data or performs an action. With a webhook, the provider initiates the interaction because it has detected an event.

This pattern appears in many connected products. A code host can notify a build system about a push. A commerce platform can notify a fulfillment system about an order. A publishing service can notify a dashboard that a post succeeded or failed. For broader integration patterns, see this guide to APIs for social media.

Why the pattern remains useful

Webhooks don't eliminate APIs. They complement them. A webhook tells you that something happened, while an API often gives you the tools to fetch complete state, retrieve related records, or issue a follow-up command.

The architectural benefit is selective traffic. When nothing changes, the provider doesn't need to send an event and the consumer doesn't need to ask for one. When something does change, the consumer receives a notification and can react quickly. That publish/subscribe shape is lightweight enough for a straightforward SaaS integration, yet flexible enough to connect independent systems across the internet.

Anatomy of an HTTP POST Payload

A webhook delivery looks like an ordinary HTTP request, but its meaning comes from the event that caused it. Consider an online store that needs to tell a fulfillment service when a new order is placed.

First, the store registers the fulfillment service's callback URL and subscribes to order-created events. When a customer completes checkout, the store creates an event, builds a payload, and sends an HTTP POST to the registered endpoint.

What the provider sends

The request normally contains three useful layers:

• The method and destination: The provider sends POST to the callback URL over HTTPS.
• Headers: These can identify the event, describe the content type, and carry a signature or timestamp.
• The body: The body usually contains structured event data, often JSON, including an event type, metadata, and the affected record.

A conceptual payload might identify an event such as order.created, include an event identifier, and provide order information such as the customer reference, line items, and fulfillment details. The exact field names depend on the provider. Your handler should follow that provider's schema rather than assuming every webhook uses the same structure.

Headers matter as much as the body. A signature lets the receiver check whether the payload came from the expected provider and whether the raw content changed in transit. An event ID gives your application a stable value for deduplication and troubleshooting. A timestamp can help the receiver assess whether the delivery is fresh.

What the receiver does

The receiver's work should follow a deliberate order:

1. Accept the request and preserve the raw body. Signature verification often depends on the exact bytes the provider sent, not a reserialized version of the parsed JSON.
2. Validate authenticity. Check the provider's signature according to its documented algorithm. Reject an invalid request before triggering business logic.
3. Read the event metadata. Identify the event type and stable event ID.
4. Record the delivery. Store enough information to trace the request and recognize a duplicate.
5. Acknowledge quickly. Return an HTTP 2xx response once the event has been durably accepted.
6. Process the business action. A worker can reserve inventory, create a shipment, or update an internal record.

The acknowledgment isn't merely a courtesy. It tells the sender that the receiver accepted responsibility for the event. A non-2xx response can cause retries in many webhook systems, so the response should reflect whether your application accepted the delivery.

A fast acknowledgment doesn't mean you should pretend success when the request is invalid. Authentication and basic validation must happen before acceptance. The important distinction is between accepting a valid event into durable infrastructure and performing every downstream action during the original HTTP request.

This short video offers a visual introduction to the request flow:

Webhooks vs Polling vs Message Queues

A fulfillment platform receives an order update while its team is offline. The integration still needs to capture the event, avoid duplicate work, and recover if a service becomes unavailable. Choosing between polling, webhooks, and message queues determines which system detects the change and which system carries the operational burden.

Polling has your application ask an API whether anything changed. It works when a provider offers no webhook support, when you need to retrieve a collection, or when periodic reconciliation matters more than immediate reaction. The trade-off is repeated traffic and a delay between checks. A scheduled job can also compare provider state with local state after an outage, deployment, or missed event.

Webhooks reverse the direction. The provider sends an HTTP event to your endpoint when it detects a change. This reduces unnecessary requests and enables near real-time workflows, but your team must operate a publicly reachable receiver, verify requests, handle provider retries, and make repeated deliveries safe. The inbound endpoint becomes part of your production boundary.

Message queues place a broker between producers and consumers. The broker can absorb bursts, let several workers consume the same event stream, isolate a failing consumer, and give your team more control over acknowledgment and replay. It also introduces broker operations, consumer coordination, monitoring, and additional failure modes.

Integration pattern comparison

These patterns can work together. A provider can deliver an event over HTTP, while your endpoint places it into an internal queue. The external integration keeps a simple protocol, and your application gains durable buffering, controlled workers, and room to absorb traffic spikes. This Webhook delivery and queue-based architecture describes that architectural combination.

Use the pattern that matches the responsibility your system can reliably carry. Choose a webhook when the provider detects events and your application needs to react quickly. Add a queue when workers need buffering, controlled fan-out, or independent failure handling. Choose polling when the provider cannot push events or when verifying current state is more important than immediate notification.

Designing for At-Least-Once Delivery

A webhook can create an order successfully and still return a timeout to its sender. From the provider's perspective, the delivery failed, so it sends the event again. Your system may then receive a duplicate even though the first attempt already changed business data.

That failure window makes exactly-once delivery an unsafe assumption. Reliable integrations generally plan for at-least-once delivery, where retries and uncertain network responses can produce multiple deliveries of one event. (Webhook idempotency guidance)

Make repeated delivery harmless

Idempotency means that processing the same event again does not create an unintended second side effect. A payment should not be charged twice, an order should not enter fulfillment twice, and a publishing event should not create duplicate content.

Use a stable event ID or idempotency key as the record of that event:

• Read the event ID from the payload or delivery metadata.
• Check durable storage before running side effects.
• Record the identifier safely during acceptance or processing.
• Skip the side effect if the identifier was already handled.
• Return success for a known duplicate so the provider stops retrying a valid delivery.

The uniqueness check must work across restarts and application instances. An in-memory set disappears when a process restarts and cannot reliably coordinate several workers. A durable database record or queue-backed store can enforce uniqueness while concurrent deliveries are being processed.

Event order needs its own decision. A customer update may arrive before the customer-created event if the earlier delivery failed. Unless the provider documents ordering guarantees, treat arrival order as uncertain. Where order affects the result, retain event state, use provider metadata, or retrieve the current resource before applying a destructive change.

Keep the edge fast

The HTTP handler should validate the request, durably accept the event, and acknowledge it. Slow work, such as calling another SaaS API, generating media, or sending notifications, belongs behind durable storage and worker processing.

Exponential backoff spaces out retry attempts, giving a recovering receiver time to accept traffic without being overwhelmed. Workers also need to separate transient failures from permanent ones. A downstream timeout may merit another attempt, while malformed data should move to quarantine for inspection.

The production contract: Verify the request, record the event, acknowledge quickly, and make every side effect safe to repeat.

Logs should capture the provider, event type, event ID, receipt time, validation result, processing status, and retry context. These fields let operators distinguish a duplicate delivery from a new business action and trace an event that was accepted but never completed.

Securing Endpoints Against Replay Attacks

A webhook endpoint is an internet-facing input. Anyone who can reach the URL may try to send a fabricated payload, modify a legitimate payload, or resend an old valid request. A shared secret helps, but production security requires more precise verification.

Start with transport security. Accept webhook traffic over HTTPS, and keep the endpoint separate from ordinary browser authentication flows. The provider needs a machine-to-machine route, not a session-based login page.

Verify the exact request

Many providers sign the payload with HMAC-SHA256. The provider calculates a digest from the raw request body and a signing secret, then sends the result in a header. Your receiver calculates the digest independently and compares the values with a timing-safe comparison function. (Webhook security fundamentals)

Preserve the raw body before your framework parses and re-encodes it. Even semantically identical JSON can have different bytes, and signing the parsed representation may produce a different digest from the provider's signature.

A verification sequence looks like this:

1. Read the raw body and signature headers.
2. Check that the required headers exist and have the expected format.
3. Calculate the HMAC with the stored signing key.
4. Compare signatures using a timing-safe function.
5. Reject the request before parsing business data if verification fails.
6. Log a safe reason and correlation identifier, never the secret.

Don't rely on a user-agent header as proof of identity. Header validation can add context, but a signature is the control that demonstrates the sender knew the secret.

Make old requests unusable

Replay attacks use a previously valid request again. Timestamp validation limits that window. If the provider includes a timestamp, verify that it falls within the freshness policy documented for the integration. Some systems also include a nonce or unique delivery identifier, which you can store and reject when seen again.

Signing keys need lifecycle management. Store them in a secrets manager, support a controlled rotation period, and remove old keys after all active senders have migrated. CloudEvents and similar standard envelopes can also provide consistent fields such as event type, source, ID, and time, but the envelope doesn't replace authentication or authorization.

Validate the payload after signature verification. Check the event type, required fields, expected account or tenant, and allowed value ranges. Apply rate limits and size limits at the edge, then monitor rejected signatures, repeated IDs, stale timestamps, and unusual delivery patterns.

A secure webhook receiver checks both who sent the request and whether the request is still appropriate to process.

Real-World Automation and Social Publishing

A campaign may look like one action in a product, yet publishing it across social platforms starts several independent workflows. Each platform can require separate authorization, payload translation, media checks, rate-limit handling, and publication tracking. A webhook architecture keeps those provider-specific steps out of the user-facing request.

The product can accept the campaign, create platform-specific jobs, and let workers handle slow operations. Webhooks report lifecycle changes back to the product layer, so a dashboard can show whether a post is scheduled, published, partially completed, or failed without repeatedly querying every platform. The delivery is usually at least once, so each event needs an idempotency check before it changes a job record.

Engagement automation follows the same pattern. An inbound comment or message event can enter a queue, where a worker validates it, checks whether its delivery ID was already processed, selects or generates a reply, and submits that reply through the relevant official API. The webhook handler should acknowledge the event promptly rather than wait for every downstream operation. If a worker crashes after receiving the event, a retry should continue safely instead of creating a duplicate response.

Where the abstraction helps

A platform such as Mallary.ai provides a unified social media API and dashboard, with webhook management for publishing lifecycle events and automation workflows. For implementation details, see how to automate social media posting at scale. An integration layer can centralize:

• Authentication: OAuth and token refresh across connected platforms.
• Delivery control: Idempotency, retries, and durable job queues.
• Payload adaptation: Platform-specific media rules and request formats.
• Status reporting: Events that let dashboards and external workflows react to job changes.
• Workflow connections: Integrations with tools such as n8n, Zapier, and Make.

For a product team, the practical distinction is between a synchronous “publish now” button and an asynchronous publishing system. The button starts a job. The webhook-driven status flow reports what happened later, including partial outcomes that need a clear user-facing state.

That design also separates campaign strategy from integration maintenance. Marketers plan content and calls to action, while backend systems handle provider differences, transient failures, duplicate notifications, and eventual status updates. The result is a chain of explicit events, durable records, and carefully managed acknowledgments, not an assumption that every platform responds immediately.

Testing and Debugging Local Endpoints

Webhook bugs often hide in the gap between your local server and the provider's infrastructure. A browser request may work perfectly while the actual integration fails because the signature uses the raw body, the provider sends an unexpected header, or your handler takes too long to acknowledge.

Start with a request inspection tool. A disposable endpoint such as Webhook.site or RequestBin can show the exact method, headers, and payload a provider sends before you write parsing logic. This separates provider configuration problems from application bugs.

For local code, a tunnel gives the provider a public HTTPS address that forwards traffic to your development machine. ngrok is widely used for this workflow, while Cloudflare Tunnel offers another tunneling approach. Both let you test an endpoint without deploying every change to a shared environment. Protect test credentials and avoid sending real customer data through a disposable development route.

A practical debugging loop

Use a short, repeatable cycle:

1. Capture a real test delivery. Use the provider's test dashboard or event trigger.
2. Log raw input safely. Record headers, event ID, content type, and body shape without exposing secrets.
3. Replay the request. Send the captured payload to your local handler with an HTTP client such as Postman or curl.
4. Test invalid signatures. Confirm that altered bodies and incorrect signatures are rejected.
5. Test duplicate events. Deliver the same event ID repeatedly and verify that side effects occur only once.
6. Simulate slow processing. Confirm that the receiver acknowledges quickly while a worker handles the longer task.
7. Inspect provider delivery history. Compare the provider's recorded response with your application logs.

A provider-specific CLI can make this faster when one exists. Provider dashboards are also valuable because they often show delivery attempts, response codes, payloads, and replay controls. Use those tools to test both the happy path and the failure path.

For teams connecting automation tools, this guide to integrating with Zapier offers a useful example of how external workflows depend on clear triggers and predictable event handling.

Don't treat a successful local POST as proof of production readiness. Test malformed JSON, missing headers, stale timestamps, duplicate identifiers, downstream timeouts, queue failures, and provider retries. A webhook integration is ready when it behaves correctly under uncertainty, not merely when it accepts one sample payload.

Mallary.ai provides a developer-first social media automation platform with a unified API and dashboard for publishing, engagement, analytics, bulk uploads, and webhook-driven workflow updates across major social platforms. Visit Mallary.ai to explore how it can handle platform-specific integration work while your product focuses on reliable automation experiences.