# Decision guide: Webhooks vs polling

> Choose the optimal data delivery strategy for your integration with interactive decision trees. Compare real-time webhooks vs polling APIs for transactions, boarding, and reporting use cases

<AudienceInfo audiences={["developers", "partners"]} />

When building your integration with Payabli, you might wonder whether to use real-time webhook notifications or to poll API endpoints for status updates, reconciliation, and system integration. This guide helps you choose between using Payabli's real-time webhook notifications or polling APIs based on your specific use case and requirements.

## Decision trees

Use these interactive decision trees to walk through the best approach for handling notifications and status updates in your integration.

### Payment notifications

This decision tree helps you determine the best approach for getting payment notifications and status updates from Payabli.

<WebhookPollingTree />

### Merchant and application status

This decision tree helps you determine the best approach for getting boarding status updates from Payabli.

<MerchantStatusTree />

## Recommended strategy by use case

Choose the right combination of webhooks and polling based on your needs. Here's a quick reference to help you decide:

| **Use case**                  | **Recommended approach**                                                |
| ----------------------------- | ----------------------------------------------------------------------- |
| Invoice payment confirmation  | `InvoicePaid` webhook + daily polling backup                            |
| Real-time transaction success | `ApprovedPayment` webhook + periodic audit polling                      |
| Vendor payout tracking        | `PayoutPaid` webhook + weekly reporting polls                           |
| Daily reconciliation          | Poll `/Query/transactions` with date filters                            |
| Dashboard and analytics       | Webhooks for real-time + polling for aggregates                         |
| Missed event recovery         | Background polling to fill gaps                                         |
| Customer receipts             | `ApprovedPayment` or `InvoicePaid` webhooks only                        |
| Financial reporting           | Scheduled polling with Reporting Engine                                 |
| Merchant onboarding status    | `ActivatedMerchant` webhook + polling for application status and audits |

## Webhooks

Webhooks are ideal when you need immediate, event-driven responses to payment activity. They provide the fastest way to update your systems and respond to customer actions. Use webhooks when:

* You want real-time updates for events such as marking invoices as paid, showing receipt screens.
* You're processing autopays, external invoices, or embedded checkouts.
* You're building event-driven systems. For example, when triggering next actions in a workflow.
* You need to notify customers immediately about payment status.
* You're integrating with real-time analytics or monitoring systems.

Webhooks are reliable when:

* You respond to each event with proper HTTP response codes
* You support retries and implement idempotent event handling
* Your webhook endpoints have high uptime and fast response times
* You handle webhook authentication and validation properly

### Core webhook events

Understanding which webhook events correspond to different payment flows helps you choose the right notifications for your integration.

| Flow                | Event name          | Trigger description                                                                 |
| ------------------- | ------------------- | ----------------------------------------------------------------------------------- |
| Invoice paid        | `InvoicePaid`       | Triggered when an invoice is successfully paid through autopay                      |
| Manual charge       | `ApprovedPayment`   | Triggered when a payment is approved via the `getPaid` API or an embedded component |
| Deposit/funding     | `TransferSuccess`   | Notifies when a Pay In transfer was successful                                      |
| Payout to vendor    | `PayoutPaid`        | Triggered when a payout to vendor is successfully processed and redeemed            |
| Tokenization        | No webhook events   | Poll `/TokenStorage` endpoint if needed                                             |
| Merchant activation | `ActivatedMerchant` | Triggered when a merchant is fully activated and ready to process payments          |

### Webhook best practices

Follow these best practices to build reliable webhook and polling implementations.

* Implement idempotent processing to handle duplicate events gracefully.
* Use proper HTTP status codes and return 200 statuses for successful processing.
* Set up retry mechanisms to handle temporary failures with exponential backoff.
* Validate webhook signatures to ensure events are from Payabli.
* Log all webhook events to maintain an audit trail for troubleshooting.

## Polling

Polling provides reliable, predictable data access and is excellent for batch processing, reconciliation, and systems that don't require immediate updates. Use polling when:

* You want to audit, reconcile, or backfill transaction data
* You need to recover from missed webhook events (server downtime, delivery failures)
* You're building batch reports, dashboards, or analytics systems
* You prefer simpler implementation without webhook infrastructure
* You need historical data analysis or trend reporting

### Core polling endpoints

Polling endpoints allow you to query transaction and payout data at your convenience. Here are the key endpoints:

* `/Query/transactions` - Query transactions by date range and filters
* `/Invoice` - Get invoice status and payment details
* `/Payout/query` - Check payout status and settlement information
* `/MoneyIn/details/:transId` - Get detailed transaction information
* `/Boarding/read/:appid` - Get application status and details

### Polling best practices

Follow these best practices to build reliable polling implementations.

* Implement rate limiting to respect API rate limits and use appropriate intervals.
* Store last processed timestamps to track what data you've already processed.
* Use pagination to process large result sets efficiently.
* Use date range filters to minimize data transfer and processing overhead.
* Implement error handling to gracefully handle API errors and network issues.

## Quick reference

This section provides quick links to relevant API endpoints, webhook events, and integration guides mentioned in the decision tree and throughout this guide.

<AccordionGroup>
  <Accordion title="Webhook Management">
    **API References:**

    * [Create notification API](/developers/api-reference/notification/add-notification)

    **Integration Guides:**

    * [Manage notifications](/guides/pay-ops-developer-notifications-manage)
    * [Notifications and reports overview](/guides/pay-ops-notifications-webhooks-overview)
  </Accordion>

  <Accordion title="Webhook Events">
    **Webhook Payloads:**

    * [InvoicePaid webhook payload](/guides/pay-ops-webhooks-payloads#invoicepaid)
    * [ApprovedPayment webhook payload](/guides/pay-ops-webhooks-payloads#approvedpayment)
    * [TransferSuccess webhook payload](/guides/pay-ops-webhooks-payloads#transfersuccess)
    * [PayoutPaid webhook payload](/guides/pay-ops-webhooks-payloads#payoutpaid)
    * [Pay In webhooks payloads](/guides/pay-ops-webhooks-payloads#pay-in-events)
    * [Pay Out webhooks payloads](/guides/pay-ops-notifications-webhooks-overview#pay-out-events)
    * [Boarding events webhooks payloads](/guides/pay-ops-webhooks-payloads#boarding-events)
  </Accordion>

  <Accordion title="Polling Endpoints">
    **API References:**

    * [Get transaction details API](/developers/api-reference/moneyin/get-details-for-a-processed-transaction)
    * [List transactions for paypoint](/developers/api-reference/query/get-list-of-transactions-for-an-entrypoint)
    * [Get list of payouts for paypoint](/developers/api-reference/query/get-list-of-payouts-for-entrypoint)
    * [Get boarding app by ID](/developers/api-reference/boarding/get-boarding-application-by-id)

    **Integration Guides:**

    * [Reporting overview](/guides/pay-ops-reporting-overview)
  </Accordion>

  <Accordion title="Reporting & Analytics">
    **Integration Guides:**

    * [Use reporting endpoints](/guides/pay-ops-reporting-overview)
    * [Manage subscriptions (autopays) with the API](/guides/pay-in-developer-subscriptions-manage)
    * [Manage payouts](/guides/pay-out-developer-payouts-manage)
  </Accordion>

  <Accordion title="Payment Processing">
    **API References:**

    * [Make transaction via the API](/developers/api-reference/moneyin/make-a-transaction)

    **Integration Guides:**

    * [Make a sale transaction](/guides/pay-in-developer-transactions-create)
  </Accordion>
</AccordionGroup>