Webhooks vs scheduled API polling: Use webhooks when the source sends events and you have a receiving endpoint.; Polling is better when events aren't available or a periodic state snapshot suffices.; Recovery plans are essential for both—neither method guarantees all changes.
Image: Workflow Automation Guide

Workflow Design

Part of APIs and webhooks in automated workflows

Webhooks versus scheduled API polling

Choose between a webhook and scheduled API polling by checking event coverage, scan behaviour, timing and recovery.

Desk Integration · · 4 min read

Choose a webhook when the source sends the event you need and you can operate a receiving endpoint. Choose scheduled API polling when that event is unavailable, or when a periodic view of current state is enough. Compare the exact source contracts: neither method automatically captures every change or recovers missed work.

Compare the two methods

Decision pointWebhookScheduled API polling
StartThe source sends a subscribed event.The workflow calls an API on a schedule.
Available dataThe notification may require a further API lookup.The endpoint may return a page or current snapshot.
Idle periodsNo delivery is needed when no subscribed event occurs.Scheduled checks continue even when nothing has changed.
RecoveryCan failed or missed deliveries be found and replayed?Can the API identify work missed since the last completed scan?

These are operating questions, not timing guarantees. GitHub describes webhooks as receiving data as it happens rather than polling an API. Check the selected sender and workflow platform for actual timing and limits.

Webhook vs Scheduled API Polling: Key Differences

Start
The source sends a subscribed event.
Available data
The notification may require a further API lookup.
Idle periods
No delivery is needed when no subscribed event occurs.
Recovery
Can failed or missed deliveries be found and replayed?
Start
The workflow calls an API on a schedule.
Available data
The endpoint may return a page or current snapshot.
Idle periods
Scheduled checks continue even when nothing has changed.
Recovery
Can the API identify work missed since the last completed scan?

Work through the choice

Name the business change first. In a hypothetical order workflow, an “order updated” event may be broader than the state change that should trigger an action. Check the subscription's event coverage and whether the payload identifies the order. If the decision needs details the event omits, plan an API lookup.

For polling, determine whether the endpoint offers a documented change filter or cursor. If it only returns current state, decide whether that is sufficient; it may not expose every transition between scans.

Where results are paginated, process the required pages before marking a scan complete. Check ordering and filter semantics before advancing a saved position, especially when records can change during the scan.

Compare acceptable delay and request work. A shorter interval makes more requests, including empty checks. A webhook removes those scheduled checks but requires a receiver, sender verification and a recovery plan. Check the relevant API allowance, subscription limits and platform behaviour before choosing an interval or endpoint.

Choosing Between Webhooks and Scheduled API Polling

  1. Name the business change firstIn a hypothetical order workflow, ensure the event covers the required state change.
  2. Check event coverage and payloadVerify if the webhook payload includes necessary details like order ID.
  3. Plan for missing dataIf details are missing, plan a follow-up API lookup.
  4. Evaluate polling optionsDetermine if the endpoint supports change filters or cursors.
  5. Handle paginationProcess all required pages before marking a scan complete.
  6. Balance delay and costShorter intervals increase requests; webhooks reduce scheduled checks but need receiver setup.

Plan recovery

Ask how the sender reports failed deliveries and whether it retries. GitHub says it does not automatically redeliver failed webhook deliveries. Authorised users can redeliver deliveries from the past three days, subject to webhook type and permissions. These are GitHub rules, not general webhook guarantees.

For polling, save a scan position only after the work required for that range is accounted for. If a request fails partway through, repeat the unfinished range safely. A reconciliation scan can complement a webhook if the source API offers a trustworthy way to find records the workflow should have handled.

Record the chosen event or endpoint, acceptable delay, scan or replay rule, and owner of missed-work review. If neither method exposes the required business change reliably, resolve that source-system gap before automating its downstream effect.

Recovery Planning for Webhooks and Polling

  • Check sender's failure handlingGitHub does not automatically redeliver failed webhooks.
  • Review redelivery capabilityAuthorized users can redeliver deliveries from the past three days.
  • Save scan position safelyOnly after completing all work for that range.
  • Use reconciliation scansIf the source API offers a reliable way to detect missed records.
  • Document key decisionsRecord event/endpoint choice, acceptable delay, scan rules, and ownership of missed-work review.

More from Workflow Design