Webhooks Explained for Business Analysts: Polling, Retries, Signatures and Requirements

How webhooks work, compared with polling

Most integrations need one system to learn about a change in another system. There are two common ways to do this: polling and webhooks. If you are new to integrations, read APIs for business analysts first and then come back here.

Polling: you keep asking

With polling, your system calls the provider's API on a schedule, for example every few minutes, and asks: has the status of this payment changed? Most of the time the answer is no. Polling is simple to build and easy to control. But it is slow, because the customer waits until the next check, and it is wasteful, because many calls return nothing new.

Webhooks: the provider tells you

With a webhook, your team gives the provider a URL, called the webhook endpoint. When an event happens, such as a payment succeeding or failing, the provider sends an HTTP POST request to that URL. The body is usually JSON that describes the event. Your system reads it, does its work and replies with a success status code to say 'got it'.

Think of a courier. Polling is you walking to the post office every hour to check for a parcel. A webhook is the courier ringing your doorbell. But the courier may ring twice, may come back later if you do not answer, and you should check their ID before you open the door. Those three ideas (retries, duplicates and verification) are exactly what a BA must capture.

In practice, many teams use both: webhooks for speed, plus a scheduled check (often called a reconciliation job) that catches anything the webhook missed.

Retries, duplicates and signatures in plain English

Retries

A webhook counts as delivered only when your endpoint replies with a success code (a 2xx HTTP status code) within a time limit set by the provider. If your server is down, slow or returns an error, the provider tries again later, often with longer gaps between attempts. After the last retry it gives up. Every provider has its own retry rules, so the BA should find them in the provider's documentation and record them.

Duplicates

Retries create duplicates. Imagine your system processed a payment event but crashed before it replied. The provider thinks delivery failed and sends the same event again. Many providers describe this as at least once delivery: you get each event at least once, and sometimes more. The fix is a business rule as much as a technical one: process each event ID once and ignore repeats. Developers call this idempotency.

Events can also arrive out of order. A 'refund created' event might land before the 'payment succeeded' event it refers to. Ask the team what the system should do in that case, and write the answer down.

Security signatures

Your webhook endpoint is a public URL, so anyone who finds it could send a fake 'payment succeeded' message. To stop this, providers usually sign each message. The provider and your system share a secret key. The provider uses the key to create a signature from the message body and sends it in a header. Your system recalculates the signature with the same key. If the two match, the message is genuine and unchanged. Many providers also add a timestamp so an old message cannot be replayed later.

You do not need to understand the cryptography. You do need to make sure the requirement exists: reject any message whose signature is missing or does not match, and log it.

How to capture webhook requirements, step by step

Webhook work often lands with developers alone, and business rules get lost. Use these steps to make sure the business side is covered. Integration thinking like this is one of the skills described in our business analyst skills guide.

1. List the business events. Which events matter? For payments, typically succeeded, failed, refunded and disputed. Leave out events nobody needs.
2. Define the action for each event. What changes in your system, who is notified and what the customer sees.
3. Map the fields. Agree which payload fields map to your data, such as the payment reference to the order, plus amount and currency. Record this in the API contract.
4. Write the duplicate rule. State that each event ID is processed once, and list what the customer must never get twice: emails, receipts, stock deductions.
5. Capture retry and timeout behaviour. Record the provider's retry rules and the reply time your endpoint must meet.
6. Require signature checks. Messages with a missing or wrong signature are rejected and logged. Ask who owns the secret key and how it is changed.
7. Plan the fallback. Decide how missed events are caught, for example a scheduled reconciliation that polls the provider.
8. Define monitoring and alerts. Who is alerted when deliveries keep failing, and where support staff can see failed or rejected events.
9. Write testable acceptance criteria. Cover the happy path, a duplicate, an invalid signature and a missing event. See acceptance criteria with Gherkin for the format.

Many of these are rules and non-functional requirements. They rarely appear in the first draft of a user story, which is exactly why the BA has to ask for them.

Worked example: moving a payment flow from polling to webhooks

Saffron Lane Tutors is a fictional online tutoring company. Parents book a course and pay through PayBridge, a fictional payment provider. Today the booking system polls PayBridge every 10 minutes to check payment status. A parent who pays for a ₹1,500 course can wait up to 10 minutes for a confirmation, and the support team gets calls from parents who think the payment failed.

The sponsor wants confirmation within a minute. The team decides to use the payment.succeeded and payment.failed webhooks, and to keep a nightly reconciliation job as a safety net. PayBridge's documentation says it expects a 2xx reply within 10 seconds and retries up to 5 times over 24 hours. So each event gets at most 6 delivery attempts: the first try plus 5 retries.

Nadia then wrote the two riskiest rules as Gherkin scenarios so Riya could test them directly:

Feature: PayBridge payment webhook

  Scenario: Duplicate payment event is ignored
    Given booking SLT-2209 for 1500.00 INR was confirmed by event evt_1042
    When PayBridge sends event evt_1042 again
    Then the system replies with a success status
    And the booking stays confirmed
    And no second confirmation email is sent

  Scenario: Message with an invalid signature is rejected
    Given booking SLT-2209 is awaiting payment
    When a payment.succeeded message arrives with a signature that does not match
    Then the system rejects the message
    And the booking stays awaiting payment
    And the rejected message is logged for review

After the change, test bookings were confirmed within seconds instead of up to 10 minutes. The nightly reconciliation compares every PayBridge payment from the last 24 hours with the bookings, so an event lost after all 6 attempts is still caught the next morning.

Common mistakes BAs make with webhooks

• Assuming each event arrives once. It will not. Without a duplicate rule, customers get double emails or double credits.
• Letting slow work happen before the reply. If the system sends emails or calls other services before replying, the provider may time out and retry.
• Postponing the signature check. Teams sometimes skip it 'for now' to save time. A fake success message could confirm an order that was never paid.
• Having no fallback. Retries eventually stop. Without a reconciliation check, a missed event means a paid customer with an unconfirmed order.
• Ignoring event order. A refund can arrive before the payment it refers to. Decide whether to wait, store it or flag it.
• Forgetting the people side. Support staff need a way to see failed and rejected events and to answer customers who call.
• Copying provider examples without checking the version. Payloads change over time. Record the version you integrated against in the contract.

Most of these mistakes come from treating webhooks as a purely technical topic. Each one has a business consequence, and that is where a BA adds value.

Checklist: webhook requirements before development starts

Use this checklist in refinement before a webhook story moves into a sprint. If any item has no answer, raise it as an open question.

Frequently asked questions