For digital code delivery, webhooks push the order result to you the moment the provider issues it, while polling has you ask for status on your own schedule. Webhooks win on latency, polling wins on control and simplicity, and production systems usually run both: webhook as the fast path, polling as the safety net.
The gift card context sharpens the trade-off. Most orders complete in seconds, but some queue behind stock checks or risk review, and the whole time a customer is standing at your checkout waiting for a code they have already paid for.
How each model behaves at the checkout
With a webhook, the provider calls an endpoint you host as soon as the order resolves. Your customer sees the code within a second or two of issuance, which for the fast majority of orders means the checkout barely pauses. The price is an inbound dependency: your endpoint must be up, reachable and correct, and a delivery that fails on your side may or may not be retried on a schedule you control.
With polling, you query the order status on a timer until it resolves. Nothing about your availability affects delivery, and debugging is a matter of reading your own request log. The price is latency and load: poll every ten seconds and your median delivery slips by five; poll aggressively across thousands of open orders and you spend your rate limit asking questions whose answer is still “pending”.
| Criteria | Webhooks | Polling |
|---|---|---|
| Latency | Seconds; near-instant delivery | Bounded by poll interval |
| Reliability | Depends on your endpoint’s uptime and the provider’s retry policy | Self-controlled; survives your own downtime |
| Implementation effort | Public endpoint, signature checks, dedupe store | A scheduler and a status call |
| Failure modes | Missed, duplicated or out-of-order events | Stale status between polls; rate-limit pressure |
The hybrid pattern
Run the webhook as the primary path and keep a scheduled poll as the sweep. The webhook resolves most orders in seconds; the poll wakes every minute or two, picks up any order still marked pending past its expected window, and asks the provider directly. If the webhook was missed (your endpoint was deploying, a proxy dropped it, the provider’s delivery gave up), the sweep closes the gap without anyone paging.
This gives you the latency of push with the completeness of pull, at the cost of one extra scheduler. Every mature code integration converges here eventually; the integration guide treats it as the default architecture rather than a refinement.
Handle every event as a possible duplicate
Once two paths can resolve the same order, duplication stops being an edge case. A webhook may arrive twice, arrive after the poll already resolved the order, or arrive out of order with a stale status. Your handler needs the same discipline as the ordering side: process each event against the order’s current state, apply it only if it moves the order forward, and make reprocessing a no-op. Deliver-the-code logic in particular must run exactly once per order, however many signals arrive.
State transitions help. An order that is already “delivered” ignores everything; a “pending” order accepts “completed” or “failed” and nothing else. Events that fit nowhere go to a log for humans, alongside the other anomalies covered in order failures.
Verify before you trust
A webhook endpoint is a public URL that accepts money-bearing news, so authenticate every delivery. Verify the provider’s signature (typically an HMAC over the payload with a shared secret), reject anything unsigned or stale, and rotate secrets the way you rotate credentials. Then go one step further: treat even a valid webhook as a notification, not as truth. Before releasing a code to a customer, confirm the order state by calling the provider’s API. A forged or replayed event should, at worst, trigger a harmless lookup.
The same caution applies in reverse: never put the code itself in logs while handling the event. The payload carries a bearer instrument, and your webhook handler is one of the few places it passes through in plain text.
Frequently asked questions
Are webhooks better than polling?
For code delivery, webhooks are better at latency and polling is better at reliability under your control, so the practical answer is both. Use the webhook to deliver codes seconds after issuance, and a scheduled poll to sweep for orders the webhook missed. Only low-volume integrations get away with polling alone, and pure webhook setups with no sweep eventually strand an order.
What happens if I miss a webhook?
The order completes on the provider’s side, but your system still shows it pending and the customer has no code. Providers often retry failed deliveries for a while, though policies differ and none retry forever. This is why a polling sweep matters: a job that re-checks any order pending past its expected window will find and resolve the missed event within minutes, without manual intervention.
How do I verify a webhook is genuine?
Check the cryptographic signature the provider sends with each delivery, usually an HMAC of the payload computed with a secret only you and the provider hold, and reject events whose signature or timestamp fails. Then confirm the order state via the provider’s API before acting on it. Signature checks stop forgeries; the confirmation call stops replays and stale events from moving money-bearing state.
How often should I poll a gift card API for order status?
In a hybrid setup, a sweep every minute or two is enough: it queries only the orders still pending past their expected completion window, so the request volume stays small. Polling as the sole delivery path needs shorter intervals and pays for them, since aggressive polling across many open orders burns rate limit on questions whose answer is still “pending”.
How do I handle duplicate webhook events for code delivery?
Make the handler state-driven: check the order’s current status, apply the event only if it moves the order forward, and treat reprocessing as a no-op. An order already marked delivered ignores everything that arrives later. The deliver-the-code step in particular must run exactly once per order, because the payload carries a bearer instrument and a duplicate email doubles the exposure.