What Are Payment Webhooks and Callbacks?

Webhooks and callbacks are how a payment provider tells your system that something happened: a DebiCheck mandate was authenticated, a collection was unpaid, a card payment settled. Instead of your system repeatedly asking for updates, the provider sends an HTTP request to an endpoint you host whenever a status changes.

Because so many South African payment outcomes are asynchronous, callbacks are usually the primary channel for final results. Getting the receiving side right is one of the most important parts of a payments integration.

How do payment webhooks work?

1. You register a callback URL with the provider, typically per environment.
2. When a mandate or payment changes state, the provider sends an HTTPS POST to your URL with a structured payload: a message ID, the event type, your original reference and the new status with its reason code.
3. Your endpoint acknowledges receipt, usually with an HTTP 200 response.
4. If the provider does not receive an acknowledgement, it retries delivery on a backoff schedule for a defined period.

How do you verify that a webhook is authentic?

Never trust an inbound request just because it arrived at your endpoint. Verify it using the mechanisms your provider supports:

• Request signatures: the provider signs the payload (for example with an HMAC or asymmetric signature) and you verify the signature against the raw request body before parsing it.
• Mutual TLS (mTLS): both sides present certificates, so only the provider can establish a connection.
• IP allow-listing: a supporting control, useful alongside signatures but weak on its own.

Also check timestamps to reject stale or replayed messages. Signature and authentication mechanics are covered in more depth in API authentication and signatures.

How should your endpoint behave?

• Acknowledge fast: validate the signature, persist the raw event, return 200, and do the heavy processing asynchronously. Slow endpoints cause timeouts and unnecessary retries.
• De-duplicate by message ID: retries mean you will receive the same event more than once. Record processed message IDs and ignore repeats, as described in idempotency and duplicates.
• Handle out-of-order events: an earlier status may arrive after a later one. Apply updates based on your state model, not arrival order.
• Fail safely: if your processing fails after acknowledgement, you own the recovery. If you reject the request, expect a retry.

What happens if you miss webhooks?

Endpoints go down, deployments break routes and certificates expire. Plan for gaps:

• Monitor for delivery failures and alert on sustained error rates.
• Use the provider's status query API to reconcile any payment still pending beyond its expected window.
• Where the provider offers event replay or a redelivery mechanism, know how to trigger it.
• Reconcile daily against reports or response files so missed events surface as breaks, as covered in clearing, settlement and reconciliation.

Webhooks vs polling: which should you use?

The practical answer is both: webhooks as the primary channel, with scheduled status queries as the backstop for anything still pending.

Checklist for a production-ready webhook consumer

• HTTPS endpoint with signature or mTLS verification
• Raw payload persisted before processing
• Acknowledgement within the provider's timeout
• De-duplication by message ID
• Idempotent, asynchronous processing
• Alerting on failures and a reconciliation backstop

Back to the Payment Operations hub.