← Insights

API Integration & Workflow Automation

What Is a Webhook? How It Works and When It Fails

A webhook is an automatic message one app sends another when something changes. How webhooks work, why deliveries fail, and how to design for it.

Published
Author
Cass & York Team
Series
Cass & York
Reading time
7 min read
0

A customer pays an invoice in QuickBooks at 9:14. Your field service app still shows the job as unpaid at 3:00, so a tech calls the customer to collect. Somebody was supposed to "set up the sync." Nobody can say whether it ran.

A webhook is how one system tells another that something changed, the moment it changes. The sending app makes an HTTP POST to a URL you registered, with a small message about the event: an invoice was paid, a job was created, a customer was updated. Your system receives it and acts. That's the whole idea, and most explainers stop there.

We build integrations for operators who run on tools like QuickBooks, Jobber, HubSpot and Shopify. The part that decides whether a webhook integration works is what happens when a message gets lost. This guide covers how webhooks work, how they differ from polling and APIs, and the design that keeps your systems in sync when a delivery fails.

What is a webhook, in plain terms

A webhook is an automatic HTTP request one app sends to another when a specific event happens. GitLab's definition calls it an automated HTTP callback triggered by an event. Red Hat adds the practical point: once it's set up, the receiving system stops asking the sender for updates, because the sender pushes them.

Think of it as a doorbell. Polling is walking to the front door every five minutes to check for a package. A webhook rings when the courier arrives. The doorbell tells you something is there. In many business systems, you still have to open the door and pick up the package yourself.

Three parts make up every webhook:

  1. An event subscription. You tell the sending app which events you care about, such as Invoice create and update in QuickBooks.
  2. An endpoint. A public HTTPS URL on your side that accepts POST requests.
  3. A payload. The JSON body describing what changed, plus headers that include a signature proving who sent it.

Webhook vs API vs polling

A webhook and an API work together. The API is the set of doors into a system: read this customer, create that invoice. A webhook is the notice that tells you when to use one of those doors.

Polling means your system calls the API on a schedule and asks "anything new?" It's simple and it works with any system that has an API. It also wastes most of its calls, and your data runs up to one full interval behind.

Polling

Webhook

Who starts the exchange

Your system, on a timer

The sending system, on an event

Typical delay

Up to one full interval (5 minutes on a 5 minute schedule)

Seconds

API calls used

Every interval, changes or no changes

One delivery per event

What happens on a missed check

The next poll catches it

Depends on the sender's retry policy

Works when the sender has no webhooks

Yes

No

Setup effort

Low

Endpoint, signature check, queue

Plug your own numbers into the calculator below to see the gap. Set how often you'd poll, how many systems you'd poll, and how many real changes happen in a day.

Data report

Polling spends most of its calls finding nothing new

864 polling calls a day to catch 120 changes: 86% of calls come back empty.

Requests a day

Bar chart. 864 polling calls a day to catch 120 changes: 86% of calls come back empty. Use the data point selector below to inspect exact values, or expand the data table.0216432648864Polling calls a day — Requests a day: 864Webhook deliveries a day — Requests a day: 120Polling calls a dayPolling c…Webhook deliveries a dayWebhook d…

Scroll across the graph to see all categories.

Requests a day
864
View data table
Polling spends most of its calls finding nothing new
CategoryRequests a day
Polling calls a day864
Webhook deliveries a day120

Example inputs: poll every 5 minutes, 3 systems, 120 changes a day. Polling calls = 1,440 minutes ÷ interval × systems.

Source: Example inputs for illustration

The waste matters when an API has rate limits or charges per call. The delay matters when a tech, a dispatcher or a collections clerk acts on stale data. Our default is webhooks for anything a person acts on during the day, and a scheduled pull as a safety net (more on that below).

How a webhook works, step by step

Here's the path a single QuickBooks invoice update takes into another system:

  1. Someone records a payment in QuickBooks Online.
  2. QuickBooks sends a POST to your endpoint. Per Intuit's guidance on webhooks, the payload carries the ID of the changed entity and the operation performed (for example, Invoice, 1234, Update). Amounts and status stay in QuickBooks until you ask for them.
  3. Your endpoint checks the intuit-signature header, an HMAC SHA256 signature computed with your app's verifier token, as described in Hookdeck's QuickBooks webhook guide.
  4. Your endpoint writes the event to a queue and returns HTTP 200 right away.
  5. A worker picks the event off the queue, calls the QuickBooks API to fetch invoice 1234, and updates the job in your field service app.

Step 5 surprises a lot of teams. Many business systems send thin notices on purpose and expect you to fetch the record. Stripe now recommends thin events too: Stripe's webhook docs describe a thin payload format and a method to fetch the related object. So a webhook integration is two jobs: catch the notice, then call the API.

The retry gap: what happens when your endpoint is down

Every endpoint goes down eventually. A deploy runs long, a certificate expires, a cloud region has a bad hour. What happens next depends entirely on the sender, and the policies vary far more than most guides admit.

Data report

QuickBooks gives up after about 100 minutes; Stripe keeps trying for 3 days

Hours each platform keeps retrying a webhook your endpoint failed to accept. GitHub leaves redelivery to you.

Hours

Bar chart. Hours each platform keeps retrying a webhook your endpoint failed to accept. GitHub leaves redelivery to you. Use the data point selector below to inspect exact values, or expand the data table.0 h18 h36 h54 h72 hStripe — Hours of automatic retries: 72 hShopify — Hours of automatic retries: 4 hQuickBooks Online — Hours of automatic retries: 1.7 hGitHub — Hours of automatic retries: 0 hStripeStripeShopifyShopifyQuickBooks OnlineQuickBook…GitHubGitHub

Scroll across the graph to see all categories.

Hours of automatic retries
72 h
View data table
QuickBooks gives up after about 100 minutes; Stripe keeps trying for 3 days
CategoryHours of automatic retries
Stripe72 h
Shopify4 h
QuickBooks Online1.7 h
GitHub0 h

QuickBooks window = 20 + 30 + 50 minutes. Timeouts: QuickBooks 3 seconds, Shopify 5, GitHub 10.

Source: Stripe Docs, Shopify Dev Docs, GitHub Docs, Intuit QuickBooks Connect 2016

Read the chart against your own systems. If your accounting platform gives up after about 100 minutes, a Saturday outage means lost updates by Saturday afternoon. GitHub, per its docs on failed deliveries, leaves redelivery to you, by hand or with a script. Shopify retries eight times over four hours and then, according to Shopify's troubleshooting guide, can remove the subscription entirely, so nothing arrives until someone recreates it.

Response deadlines are tight as well. Intuit says to respond within three seconds (QuickBooks Connect session on webhooks). Shopify allows five. GitHub marks a delivery failed after ten. An endpoint that does the real work before replying will miss these windows on a slow day, which is why step 4 above returns 200 first and works second.

Five design rules for webhooks that hold up

These are the rules we apply on every integration.

  1. Verify the signature on the raw body. Stripe signs with the Stripe-Signature header and rejects verification if your framework has reparsed the body (Stripe). Reject anything unsigned. A public URL that triggers "mark invoice paid" is an open door otherwise.
  2. Acknowledge fast, process later. Write the raw event to a queue or table, return 200, and let a worker do the API calls. Stripe recommends an asynchronous queue to absorb spikes such as month start renewals.
  3. Expect duplicates. Senders retry, and retries create repeats. Store each event ID you've processed and skip repeats. Stripe states plainly that endpoints might receive the same event more than once.
  4. Ignore arrival order. Stripe warns that events can arrive out of order, and Intuit says older events can arrive in later notifications. Fetch the current record and compare its last updated timestamp before you overwrite anything.
  5. Run a reconciliation sweep. This is the one most teams skip. Once a night (or every hour for money data), pull everything that changed since the last sweep and compare it to your copy. Intuit's own guidance points to its Change Data Capture API for exactly this: recovering events that were missed or dropped (Intuit).

Rule 5 carries the most weight. A webhook gives you speed. The sweep gives you correctness. With both, a missed delivery turns into an update a few hours late, which an operator can live with. With webhooks alone, it turns into a record that's wrong until someone notices.

Where webhooks fit in an operator's stack

Most operators meet webhooks inside a tool before they ever write code: Zapier, Make and n8n all offer webhook triggers. That works for a handful of flows. It gets fragile when a zap carries money or job status between systems, because the retry gap and the duplicate problem still apply, and the tool's dashboard may hide them.

Here's how we decide the shape for a client:

Situation

What we build

Sender has webhooks, data drives same day work (job status, payments, dispatch)

Webhook into a queue, worker fetches the record, nightly sweep

Sender has webhooks, data feeds reports only

Scheduled pull is often enough; skip the endpoint

Sender has no webhooks

Polling with a cursor (last modified time), tuned to the API's rate limit

Data arrives as files (exports, SFTP drops)

File arrival triggers a batch job

The last row comes from experience. On the New York Lottery data pipeline, the inputs were encrypted files moving between parties, so we built secure file ingestion and batch processing on AWS. Pick the mechanism that matches how the data actually moves.

What to ask before you turn webhooks on

If someone is setting up a webhook integration for you, these questions tell you whether it will survive a bad week:

  • Which events are we subscribed to, and which system owns each record?
  • Is every incoming request signature checked?
  • What happens to events that arrive while the endpoint is down?
  • Where are duplicates caught?
  • Is there a scheduled sweep that finds anything the webhooks missed?
  • Who gets alerted when deliveries start failing, and how fast?

If the answer to the sweep question is "we don't need one," ask what happens when QuickBooks stops retrying after its third attempt.

Getting your systems to tell each other the truth

Webhooks give you speed, so the tech, the office and the books see the same payment within seconds. The queue, the duplicate check and the nightly sweep make that speed safe to rely on.

If you have two systems that should agree and don't, show us the workflow. We'll map which system owns which record, where webhooks fit, and where a scheduled pull does the job better. You can see how we approach this on our systems integration page.

Sources

Share this article

Show us the workflow your existing software can't handle.

You don't need a technical specification. Walk us through the process, the systems involved, and where your team is losing time.

Book a Workflow Call →
Systems involved