Short answer: a webhook is the other system notifying you, polling is you checking with them on a schedule, and idempotency means the same request counts once no matter how many times it arrives. Payments marked unpaid or charged twice usually trace to these three; fixing them typically costs NT$20K–60K and 1–2 weeks.
The owner of a bubble tea brand called us: "The customer says payment went through, but the back office shows unpaid, so staff asked them to pay again, and they were charged twice." The vendor replied, "We didn't receive the webhook, we don't poll, and we didn't handle idempotency." The owner was more confused than before. These three words always appear together because together they decide whether your system knows the money arrived and whether it counts it twice.
Term 1: Webhook — the delivery app telling you "your food has arrived"
A webhook is the other system calling your system the moment something happens.
Analogy: when you order food delivery, you don't refresh the page; the app pushes "rider picked up" and "delivered."
Example: a cram school takes tuition by card. The instant payment succeeds, the payment provider (for example ECPay, or Stripe's webhooks) sends "paid" to the school's system, which marks the enrollment paid and sends a LINE message. The weakness: if your site is down for maintenance, that "call" can be missed.
Term 2: Polling — calling every 10 minutes to ask
Polling is your system regularly asking the other side whether a status has changed.
Analogy: waiting for a parcel and calling the courier every so often; ask too often and they get annoyed, too rarely and you hear late.
Example: a restaurant booking system checks unconfirmed deposits with the payment provider every 10 minutes, so a missed webhook is fixed within 10 minutes. Polling is insurance for webhooks, not a replacement, because frequent checks hit rate limits.
Term 3: Idempotency — press the elevator button five times, one elevator comes
Idempotency means the same request, sent any number of times, takes effect only once.
Analogy: pressing the elevator button once or five times brings one elevator, not five.
Example: on a slow connection a customer taps "Pay" three times, or the provider resends the same webhook twice. An idempotent system uses a unique order number or an idempotency key to recognize "already processed," so it charges once, deducts stock once and issues one invoice.
How the three fit together
Together they form a "receive it, recover it, never double it" mechanism; missing any one causes trouble.
Picture it this way: the payment provider on the left, your order system on the right. A solid arrow on top from provider to you is labeled "Webhook: push notification"; a dashed arrow below from you to the provider is labeled "Polling: scheduled check." Both arrows pass through a gate at your door labeled "Idempotency check: already processed?" Only new events update the order; duplicates are skipped.
What it means for your decisions
These items are often left off quotes, but fixing them costs far less than the incidents they cause.
| Item | If missing | Cost to add (reference) |
|---|---|---|
| Webhook receipt and verification | Paid but order not updated; manual reconciliation | NT$10K–20K |
| Polling schedule | Missed notifications never recovered | NT$5K–15K |
| Idempotent handling | Double charges, double shipments, duplicate invoices | NT$10K–25K |
At 3,000 orders a month with 0.5% errors, 15 orders a month need manual reconciliation and refunds; a year of labor and complaints often exceeds the fix.
Five questions to ask your vendor
Ask these before sign-off; if the vendor can't answer, ask for the fix.
- "Do we receive payment results by webhook, and do we verify they really come from the provider?"
- "If the site is down and misses a notification, how soon does polling catch it?"
- "If the same webhook arrives twice, could we ship or invoice twice?"
- "If a customer taps Pay three times, could they be charged three times? How do we identify the same payment?"
- "Is there a screen showing failed notifications and successful re-checks?"
FAQ
Here are the 4 questions readers ask most; the first sentence of each answer is the answer.
How is a webhook different from an API?
With an API you ask the other side; with a webhook they notify you. They work together: webhooks for real-time alerts, APIs for lookups and backfill.
Do we still need polling if we have webhooks?
Yes. Webhooks can be missed during maintenance or outages; polling every 5–15 minutes ensures no order stays stuck as unpaid.
Are double charges the payment provider's fault?
Usually not. The common cause is your system processing the same request twice without idempotency; with it, each payment counts once.
How long does it take to add all three?
Usually 1–2 weeks and NT$20K–60K, depending on the number of providers and existing code, including resend and outage tests.
Next step
Worried about gaps in your website or app payment flow? ScriptWalker (a Taiwan custom development studio working in Laravel and Flutter) offers a free 30-minute consultation to check your webhooks, polling and idempotency:
- Email: [email protected]
- Phone: 0916-224-047
- LINE: @ufv9089p