Webhook Acknowledgement

Overview

What it means and why it exists

A webhook acknowledgement is the HTTP response a receiving server sends to tell a publisher that an event delivery reached its handler according to the provider's rules. It is not a confirmation that the underlying payment succeeded.

How it works

The sender POSTs an event to a configured endpoint. The receiver authenticates the event, performs minimal durable acceptance work, and usually returns an appropriate 2xx status promptly. Heavy downstream processing, such as order fulfillment or ledger updates, can run asynchronously from a durable queue. Providers may retry when delivery fails or times out.

Technical details worth understanding

Acknowledging before the event is safely persisted risks losing the event if the server crashes immediately. Waiting to finish slow downstream tasks before acknowledging can cause unnecessary retries. The correct pattern is authenticate, check deduplication, durably enqueue or record, then acknowledge under the sender's documented expectations.

What can go wrong

Some providers interpret a 2xx response differently, so integration behavior must follow their specification. Responding 200 to a forged event is unsafe, and re-deliveries can still occur even after a successful acknowledgement. The receipt of an event must not bypass independent payment-state verification.

Practical checks

Persist the event or queue message durably before acknowledging when the provider's protocol allows it. Return promptly after authentication and basic validation rather than waiting for inventory or email jobs. Simulate an app crash after returning 200 to ensure no order event is silently lost, and deduplicate retry deliveries.

Related concepts

Payment Status API, Webhook, API Key.

Further reading

OWASP — Webhook Security.