Webhooks and event delivery: signatures, retries, ordering and replay

A webhook is a notification the bank sends to the client when something happens to a payment, so the client does not have to keep asking. When a payment is accepted, settled, credited or rejected, the bank sends an HTTP POST to a URL the client registered, with a JSON body describing the event. Webhooks are how a client learns about a payment outcome in near real time, without polling the status endpoint every few seconds. But webhooks introduce their own problems, and a payments SME must understand them, because a webhook that is lost, duplicated, or forged can cause a client to credit a customer twice or not at all. Source: webhook delivery guidance; bank API developer documentation; Stripe webhook documentation as an industry reference pattern. The webhook body carries the event type, the payment identifier, the new status, and a timestamp. For example, when a payment of EUR 25,000 is credited to the beneficiary, the bank sends an event of type payment.credited with the payment identifier PAY-20261105-8841, the status ACCC, and the timestamp. The body also carries an event identifier, a unique value for this delivery, so the client can detect duplicates. The client must acknowledge the webhook by returning a 2xx HTTP status within a short window, typically 5 seconds. If the client does not acknowledge, the bank retries. The client must not assume a webhook will arrive exactly once: it may arrive twice, or not at all, and the client must handle both cases. The defence against duplicates is the event identifier: the client stores the identifiers it has already processed, and ignores a webhook whose identifier it has seen before. Signatures prove the webhook came from the bank and was not tampered with. The bank signs the webhook body with a secret shared with the client, using HMAC SHA-256, and sends the signature in a header. The client recomputes the signature from the body and the secret, and compares it with the header. If they match, the webhook is genuine; if they do not, the webhook is forged or corrupted and the client must reject it. The client must never act on a webhook whose signature it has not verified, because an attacker who can forge a payment.credited webhook can trick the client into releasing goods or crediting a customer for a payment that never happened. The secret must be rotated periodically, and the bank must support two secrets during rotation so that webhooks signed with either the old or the new secret are accepted for a transition period. Retries and ordering are the two delivery problems a client must handle. If the client's endpoint is down when the bank sends a webhook, the bank retries with exponential backoff: after 1 minute, then 5 minutes, then 15 minutes, then 1 hour, up to a maximum number of attempts, typically 24 hours. After the maximum, the bank stops retrying and the client must enquire about the payment status through the API. Ordering is not guaranteed: a payment.accepted webhook and a payment.credited webhook for the same payment may arrive out of order, or the credited webhook may arrive before the accepted one. The client must therefore process webhooks by timestamp and state, not by arrival order: if it receives a credited event for a payment it has not yet seen as accepted, it records the credited state and does not assume the accepted event was lost. For a business analyst, the requirement is to define the event types, the delivery guarantees, the retry schedule, the signature scheme, and the client behaviour for duplicates and out of order delivery, and to test each with a real webhook. Webhook endpoint registration is a security decision, not just a configuration step. When a client registers a webhook URL, the bank must verify that the client owns that URL, typically by sending a challenge to it and requiring the client to return the challenge value. Without this verification, an attacker could register a webhook URL that points to a server it controls, and receive notifications about payments it has no right to see. The bank must also verify that the URL uses HTTPS, because a webhook sent over plain HTTP can be intercepted and read or modified. A client that registers an HTTP URL must be rejected with a clear error. For a business analyst, the requirement is to define the registration process, the verification challenge, the HTTPS requirement, and the process for changing or deleting a registered URL. For a business analyst, the requirement is to define this behaviour in the API specification, because the client builds against the specification and nothing else. Webhook delivery must be monitored like any other part of the payment flow. The bank must track, for each client, how many webhooks were sent, how many were acknowledged, how many were retried, and how many failed permanently. A client whose endpoint has been failing for a day is a client that is not receiving payment notifications, and the bank should alert it. The bank should also provide a way for the client to replay missed webhooks, for example by listing the events for a payment through the API and re-sending the ones the client missed. A client that has no way to recover missed webhooks must poll the status endpoint for every payment, which defeats the purpose of webhooks. For a business analyst, the requirement is to define the delivery monitoring, the alert thresholds, and the replay mechanism, and to test them with a real client endpoint. Further reading: webhook delivery guidance; bank API developer documentation. Last reviewed 7 November 2026.