Refund Webhook
Pronunciation: REE-fund WEB-hook
Also known as: Refund Callback, Refund Status Webhook
Definition
Refund Webhook is an asynchronous notification that reports creation or a later status change of a refund operation. It reports an event but should not be treated as proof that funds reached the recipient unless the documented terminal state has that meaning.
Overview
How it works
The principal risks include duplicate customer notifications, repeated ledger postings, refund fulfillment before finality, forged callbacks, wrong-payment attribution, and missed failure or reversal states. For Refund Webhook, the event identifier, signature result, delivery attempt, and resulting business state should remain connected throughout processing.
What matters in practice
A refund webhook reports changes in a refund instruction such as created, approved, broadcast, failed or completed. Because delivery may be duplicated or out of order, consumers should authenticate signatures, deduplicate stable event IDs and verify the latest refund status before posting a ledger adjustment. A webhook saying `initiated` must not trigger a customer-facing 'money returned' message. Refund destinations and amounts are sensitive; the receiver should not trust unverified callback content to change beneficiaries. Store links to the original payment and refund transaction for audit.
Refund-status delivery should not itself create or approve a new refund. The receiver should only update an existing identified refund and must check that the event's amount, currency and beneficiary correspond to the stored instruction. Delayed notifications and manual interventions can generate apparent state reversals; order events by a versioned source-of-truth record rather than local arrival time. The final customer communication should distinguish 'sent' from chain-confirmed receipt.
A customer may open multiple refund requests for the same original payment. Webhook consumers should key events by refund instruction as well as payment ID, and reconcile total returned value against the refundable balance. One successful partial refund must not be mistaken for completion of every pending refund on that original order.
Related glossary concepts
Example
A shop receives a refund-completed event, then an older processing event arrives after a network delay. Its versioned state machine ignores the stale transition while preserving both event records.
Comparison
A refund webhook communicates status; it does not authorize a new refund request and is not itself evidence of chain finality.
Key Takeaway
Verify the sender and payload, deduplicate by refund or event ID, preserve original payment linkage, process status transitions in order-aware logic, and reconcile against the refund system of record.
Sources
- Webhook — OxaPay (2026-08-03)
- CloudEvents Specification — Cloud Native Computing Foundation (2026-08-03)
- HTTP Message Signatures — IETF (2026-08-03)