Webhooks Plus Polling: Closing Delivery Gaps
Combine low-latency webhook delivery with bounded range reconciliation, preserving event identities and avoiding duplicate activity across the two paths.
Overview
When translating these concepts into an integration, keep the scope described by the normalized transactions api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Webhooks improve delivery latency, while polling can verify a defined historical range. A robust integration can use both without treating either delivery mechanism as the event’s identity.
Give the paths different jobs
Use webhooks for prompt notification under their delivery contract. Use range reads to reconcile completed coverage or recover missed delivery. Both paths should converge on the same durable event identities. A webhook delivery ID can identify an attempt, while the underlying chain event ID identifies the business evidence.
Worked example: an outage window
The receiver is unavailable for ten minutes. After recovery, a bounded scan covers an overlapping accepted block range and discovers missed events. Events already received through webhooks are recognised rather than inserted twice. The overlap also allows verification of the range boundary and accepted block identities.
Persist completion checkpoints
Advance the range checkpoint only after processing is durable. Test repeated webhook delivery, partial pages and a restart between write and checkpoint. Do not repeatedly scan all history on every notification. Keep coverage status separate from delivery freshness so callers can distinguish a live stream from a fully reconciled reporting range.
A practical acceptance test
Drop several webhook deliveries, then run a bounded overlapping range scan. Assert recovery of missed events and no duplication of already processed ones. Interrupt before the range checkpoint commit and repeat the scan. Coverage should advance only after durable processing, while webhook latency remains a separate operational metric.
Questions about the topic
Frequently asked questions
Should a webhook ID replace chain event identity?
No. Delivery identity and underlying event identity can differ.
Does overlap necessarily create duplicates?
Not if processing uses stable event identities and idempotent writes.
Standards & technical documentation