What Is Webhook and How It Works

Your cron job runs every thirty seconds, asks a social platform whether the post finished, receives another empty response, and fills the logs with noise. Then the post finally publishes, but your dashboard still shows the old state because the next check hasn't happened yet. You've spent compute, consumed request capacity, and still can't call the workflow real time.

That frustration explains what is webhook and how it works better than any definition. Instead of repeatedly asking whether something changed, you register a destination and let the source system notify you when the event occurs. The source sends an HTTP request containing the event, your endpoint acknowledges it, and your application reacts without an idle polling loop.

The happy path is simple. Production delivery is not. Duplicate events, retries, signature verification, replay attacks, slow handlers, and out-of-order processing are where webhook integrations either become dependable infrastructure or become another source of midnight alerts.

Table of Contents

• The Polling Headache That Hooks You on Webhooks

• What a Webhook Actually Is and the HTTP Anatomy

• Webhooks vs Polling and APIs Compared

• At-Least-Once Delivery Retries and Idempotency

  • Store the event before acting

• Payload Signing Replay Protection and Secret Rotation

  • Validate the request in an intentional order

• A Real Webhook Flow Through PostPulse

  • The decisions that matter

• The Webhook Checklist Before You Ship

The Polling Headache That Hooks You on Webhooks

A polling loop usually starts innocently. Your worker wakes up, calls a publishing API, checks whether a media upload or carousel container has moved beyond “in progress,” records the response, and goes back to sleep. Thirty seconds later, it repeats the same operation, often finding that nothing changed.

That approach has one useful property: your application controls when it asks for state. It's straightforward to reason about, and it can repair inconsistencies when an event was missed. But it also creates work when there's no news. Your logs fill with successful requests that carry no meaningful change, your rate-limit budget gets thinner, and your UI can lag behind the actual platform state.

Social publishing makes the delay especially visible. A post might complete between two polling cycles, while your user waits for a status refresh or receives a notification late. If the publishing provider updates state quickly but your worker checks only periodically, the system's perceived responsiveness is determined by the polling interval, not by the publishing event itself.

A webhook reverses that responsibility. You give the provider a reachable callback URL and subscribe to the events you care about. When the state changes, the provider sends an HTTP POST with the event data already attached. Your endpoint doesn't need to ask, “Did anything happen?” It only needs to validate the request, record it safely, acknowledge delivery, and hand processing to the right worker.

For a clear conceptual comparison before you build, this polling and webhooks guide is a useful reference. The important distinction is simple: polling asks for state, while a webhook announces a change.

What a Webhook Actually Is and the HTTP Anatomy

A webhook is an event-driven HTTP callback. One system detects an event, then sends another system an HTTP request at a URL configured in advance. The callback commonly uses POST with a JSON payload, while the receiving application returns a 2xx status to acknowledge successful delivery. This push model is the core difference between a webhook and a request-driven API, as described in this webhook definition and delivery overview.

A diagram illustrating the three steps of how a webhook works: the event, the trigger, and the request.

The request has a few practical parts:

• Method: The provider sends an HTTP POST. RFC 9110 defines POST as a method where the enclosed representation is processed according to the target resource's semantics, as explained in the HTTP POST specification.

• Endpoint: You register a URL that can receive the provider's request.

• Headers: A delivery can include content-type, user-agent, webhook-id, webhook-timestamp, and webhook-signature. Exact names vary by provider, so use that provider's contract rather than assuming every header exists.

• Body: The payload is usually JSON, with fields such as an event type, a data object, and an identifier that helps your handler deduplicate deliveries.

The Standard Webhooks specification places the webhook payload in the body of an HTTP POST, puts additional webhook metadata in headers, and treats a delivery as successful when the receiver returns a 2xx status, meaning a status from 200 through 299.

A trimmed request might look conceptually like this:

Your endpoint should return a 2xx response only after it has accepted the event safely. A non-2xx response, a timeout, or a broken connection can tell the sender that delivery needs another attempt.

There are two directions to understand. An inbound webhook is one your application receives, such as a publishing notification. An outbound webhook is one your application sends to another system after something happens inside your product.

Webhooks vs Polling and APIs Compared

The choice becomes clearer when you separate the communication patterns instead of treating webhooks as a replacement for every API call.

A request-response API is useful when your application needs a specific answer now. You call an endpoint to fetch a post, update a setting, or retrieve details. Polling uses that same request model repeatedly to discover whether state has changed. A webhook works differently. The provider initiates the request because it already knows an event occurred.

Webhooks are particularly useful for near-real-time automation, including payment notifications, code pushes, and workflow triggers. Svix's research reported webhook support in 83% of analyzed APIs in 2023, with adoption increasing to 85% in 2024, according to its State of Webhooks report. That adoption pattern suggests that webhook support has become an expected integration capability across software categories, not a specialist add-on.

The tradeoff is operational complexity. Polling is often easier to bootstrap, and it remains valuable for rebuilding state after downtime. Webhooks require a public endpoint, authentication or signature verification, retry handling, durable event storage, and a plan for duplicates.

For a social publishing workflow, a webhook can tell your application that a post completed, failed, or needs attention, while a REST API can fetch the full post record or analytics details afterward. That combination is also the basis of distribution automation with PostPulse, where event notification and on-demand retrieval serve different jobs.

At-Least-Once Delivery Retries and Idempotency

The most important production fact is this: webhook delivery is normally at least once, not exactly once. If the sender doesn't receive a successful response, it may send the same event again. A timeout, a 5xx response, or a network interruption can all create a duplicate delivery, as described in this webhook idempotency guide.

A diagram explaining at-least-once delivery, retries, and idempotency in the context of webhook communication systems.

The failure sequence is easy to miss:

1. The provider sends an event.

2. Your handler validates it and sends an email or updates a database record.

3. Your process crashes before the provider sees the acknowledgement.

4. The provider retries the event.

5. Your handler performs the side effect again.

That can mean duplicate emails, duplicate notifications, or a business action occurring twice. The receiver must therefore make processing idempotent, meaning repeated handling of the same event produces the intended result instead of repeating the side effect.

Store the event before acting

Use a stable event identifier from the payload or a delivery header such as X-Webhook-Id. Before triggering an external side effect, persist that identifier in durable storage. If the identifier already exists, acknowledge the delivery and skip the work.

A Redis record can work for this purpose when its TTL lasts longer than the provider's retry window. A relational database with a unique constraint can provide a stronger durable record. The storage choice matters less than the invariant: the deduplication decision must survive a process restart and must be atomic enough to prevent two workers from processing the same event concurrently.

Retry schedules commonly use exponential backoff and jitter, but don't hard-code a particular sequence unless the provider documents it. A resilient architecture places the received event into a durable queue, lets a worker perform the business operation, and routes persistent failures to a retry or dead-letter path. This separates capture from processing and avoids losing events when a downstream service is unavailable, as outlined in this webhook reliability engineering reference.

Your system also needs a stopping rule. The provider may stop after its documented retry policy, while your own worker can use a circuit breaker, a bounded retry process, or a dead-letter queue for manual inspection. The key is visibility. Log the event ID, attempt state, processing outcome, and error category without logging secrets or sensitive payload fields unnecessarily.

Payload Signing Replay Protection and Secret Rotation

A public webhook URL is not proof that a request came from the provider. Anyone who discovers the endpoint can send a plausible JSON body unless your receiver verifies authenticity. Production integrations should use HTTPS and a provider-supported signing scheme, then reject requests that fail validation.

The common pattern is HMAC-SHA256. The sender and receiver share a secret. The sender computes a keyed hash from the payload and relevant metadata, then places the result in a signature header. The receiver independently calculates the expected value and compares it with the received signature using a constant-time comparison function.

The exact signed message differs by provider. Some schemes sign the raw body directly. Standard Webhooks-style implementations commonly bind the payload to a timestamp, so the receiver can check both the content and when the sender created the delivery. Don't reconstruct a parsed JSON object before verification if the provider signs the raw bytes. Formatting changes can produce a different digest even when the parsed data looks equivalent.

Validate the request in an intentional order

A safe handler usually follows this sequence:

• Read the raw body: Preserve the exact bytes used for signature calculation.

• Read signature metadata: Extract the documented signature and timestamp headers.

• Check freshness: Reject timestamps outside the provider's documented tolerance window.

• Calculate HMAC-SHA256: Use the configured secret and the provider's exact signing formula.

• Compare safely: Use a constant-time comparison rather than a normal string comparison.

• Deduplicate: Check the event ID before triggering side effects.

• Acknowledge: Return a 2xx after durable acceptance.

Timestamp validation limits replay risk. If an attacker captures a valid request and submits it again later, a freshness check can reject the stale delivery. Replay protection must work with your clock-skew policy and the provider's redelivery behavior, so don't invent a tolerance window without checking the integration's documentation.

Secret rotation needs the same operational care. During a rotation window, accept signatures generated with the current secret and the previous secret, then remove the old one after all relevant senders use the replacement. Store secrets outside source control, restrict access, and avoid printing them in request logs. For broader background on bearer tokens, API keys, HMAC, and related approaches, see this guide to API authentication methods.

A Real Webhook Flow Through PostPulse

Consider a social publishing workflow. A draft is approved in a dashboard, the publishing service sends the post to linked social accounts, and the application needs to update its own record when distribution finishes. The application shouldn't keep asking every platform whether the post is complete. It should accept a completion event and use the REST API only when it needs more detail.

A diagram illustrating how a PostPulse webhook dashboard automates and confirms social media post delivery across platforms.

A representative post.published delivery can contain fields such as event_id, event_type, and created_at, plus a nested data object. That object can carry the post URL, the destination platform, and an analytics snapshot. The request headers can carry the HMAC signature, delivery timestamp, and an idempotency key.

The receiver's first job isn't to fetch analytics or send a customer notification. It's to preserve the raw request, verify the signature, and record event_id in durable storage. If the event is new, the endpoint places it on a queue and returns a successful 2xx response quickly. A worker then updates the internal publishing record, sends any user-facing notification, and asynchronously fetches additional details through the PostPulse REST API.

The decisions that matter

Where should signature verification happen? At the webhook boundary, before the event reaches business logic. That prevents untrusted data from entering the rest of the application and gives you one consistent place to handle invalid requests.

How long should processed IDs remain available? Keep them longer than the provider's documented retry period, with enough margin for operational redelivery. A short-lived cache can incorrectly treat a late duplicate as new.

What should you log? Record the event ID, event type, delivery timestamp, response status, processing duration, and failure category. Avoid logging the signing secret, full authorization headers, or unnecessary personal data from the payload.

For teams wiring visual workflows, the guide to creating PostPulse webhooks in n8n shows how a callback can feed the next automation step. The same reliability rules still apply, whether your receiver is a custom service, an n8n workflow, or another automation platform.

The Webhook Checklist Before You Ship

A webhook endpoint can look finished when it accepts one test request. Before production, review the delivery boundary, the processing path, and the operational controls separately. Each item below protects against a specific failure mode.

A checklist of five essential steps to follow when implementing webhooks, displayed as a clear infographic.

• Enforce HTTPS and current TLS: Require TLS 1.2 or higher where your infrastructure supports it. Plain or outdated transport exposes the endpoint and can make delivery fail security review.

• Respond quickly: Return a 2xx within the provider's documented timeout, and keep the request path focused on validation plus durable acceptance. Slow business logic causes avoidable retries.

• Persist before processing: Save the raw body and delivery metadata before parsing or triggering side effects. Losing the original bytes can make later signature verification and debugging impossible.

• Verify the signature: Use the provider's documented HMAC-SHA256 or equivalent scheme, check timestamp freshness, and compare signatures in constant time. Don't trust only an event type header because headers can be spoofed.

• Deduplicate by event ID: Store the unique event identifier durably and make the check atomic. Without this guard, a retry can repeat an email, database mutation, or publishing action.

• Protect the secret: Keep the signing secret outside source control and support an overlap period during rotation. Never place it in application logs or error messages.

• Limit the request: Cap inbound payload size and validate the schema before queueing work. This reduces exposure to malformed or oversized requests.

• Treat failures deliberately: Decide which validation errors should stop delivery and which processing errors should be retried. A 500 response shouldn't become an unbounded retry storm.

• Control network access where appropriate: IP allow-lists or mutual TLS can add protection for higher-risk feeds, but they shouldn't replace signature verification when signatures are available.

• Monitor the whole lifecycle: Track delivery latency, 4xx and 5xx ratios, signature failures, queue age, and dead-letter or replay depth. Alerts should identify whether the provider couldn't reach you, your endpoint rejected the request, or your worker failed afterward.

Run tests for duplicate deliveries, malformed signatures, stale timestamps, expired secrets, oversized payloads, worker crashes, and provider redelivery. A webhook that works only when every request arrives once, in order, with a healthy downstream API is still a demo.

PostPulse provides social publishing for apps, automations, and AI agents through a unified REST API, official n8n and Make.com integrations, and an MCP server, with webhook notifications for publishing workflow events. Visit PostPulse to connect webhook-driven status updates to a publishing flow that reaches your own application or automation system.