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
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:
- An event subscription. You tell the sending app which events you care about, such as
Invoicecreate and update in QuickBooks. - An endpoint. A public HTTPS URL on your side that accepts POST requests.
- 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.
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
Scroll across the graph to see all categories.
- Requests a day
- 864
View data table
| Category | Requests a day |
|---|---|
| Polling calls a day | 864 |
| Webhook deliveries a day | 120 |
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:
- Someone records a payment in QuickBooks Online.
- 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. - Your endpoint checks the
intuit-signatureheader, an HMAC SHA256 signature computed with your app's verifier token, as described in Hookdeck's QuickBooks webhook guide. - Your endpoint writes the event to a queue and returns HTTP 200 right away.
- 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.
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
Scroll across the graph to see all categories.
- Hours of automatic retries
- 72 h
View data table
| Category | Hours of automatic retries |
|---|---|
| Stripe | 72 h |
| Shopify | 4 h |
| QuickBooks Online | 1.7 h |
| GitHub | 0 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.
- Verify the signature on the raw body. Stripe signs with the
Stripe-Signatureheader 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. - 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.
- 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.
- 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.
- 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
- Receive Stripe events in your webhook endpoint, Stripe Docs, accessed Nov 2026
- Troubleshooting webhooks, Shopify Dev Docs, accessed Nov 2026
- Handling failed webhook deliveries, GitHub Docs, accessed Nov 2026
- Mastering webhooks for real time data synchronization, Intuit Developer Blog, accessed Nov 2026
- QuickBooks Connect 2016: Using webhooks to handle data changes in your app, Intuit Developer (SlideShare), 2016
- Guide to QuickBooks webhooks: features and best practices, Hookdeck, accessed Nov 2026
- What is a webhook?, GitLab, accessed Nov 2026
- What is a webhook?, Red Hat, accessed Nov 2026
Share this article