Events and webhooks
Connect account, payment and payout notifications to the right records. Verify each delivery, retain what you need to resume processing and apply each update once.
DevelopersBefore you begin
- Enabled event subscriptions for each required service
- The event format, verification requirements and delivery rules for your connection
- An HTTPS receiver, durable storage and authorized recovery lookups
- Separate sandbox and production merchant mappings
On this page
Confirm the available event types
Account, payment and funding updates describe different records. Confirm which notifications are available for your connection and keep their definitions separate. Do not apply one event family’s status values or verification scheme to another.
| Event family | Record to resolve |
|---|---|
| Account setup | Application review and required setup results. Match the application and program; approval and processing readiness are separate checks. |
| Checkout | The configured transaction result. Match the processing account, transaction and original payment attempt. |
| Funding | Deposit, instruction or batch activity, where available. Read the relevant record and status definition before updating reconciliation. |
Verify the delivery
Keep the received message available in the representation required by the verifier. Apply the authentication, signature validation or decryption required by your integration instructions, in the specified order. A parsed or reserialized JSON body is not automatically equivalent to the signed content.
| Layer | What to confirm |
|---|---|
| Subscription access | Who may configure or change event delivery. This is separate from verification of an incoming notification. |
| Delivery verification | The required authentication, signature or encryption checks, including key management and replay handling. |
| Account and environment | How the verified event is matched to an authorized merchant and the intended environment. |
Check valid and invalid event deliveries
Ask our integration team for the event verification instructions and required sandbox data. Reject altered content, invalid credentials and mismatched accounts according to those instructions. Use the specified signed content, timestamp tolerance and verification order.
Reject unverifiable deliveries
Where these checks apply, reject invalid signatures, failed decryption, unknown keys and mismatched merchants before updating an order, account or funding record. Use the response and escalation behavior defined for that subscription, retaining only safe diagnostics.
Match the event to its record
Keep the delivery record separate from the account, payment or payout it describes. One subscription can carry updates for many records, and one record can receive several legitimate updates.
| Identity | Purpose |
|---|---|
| Subscription | The configured stream of notifications. It is not a unique payment reference. |
| Delivery attempt | A particular delivery or retry, useful for tracing a notification. |
| Merchant account | The account authorized to receive the payment record. |
| Payment or operation | The transaction or related operation whose status is being reported. |
| Order or account update | The change your application may apply once, tied to the correct merchant, payment or operation and status. |
Save, acknowledge and process the event
- 01 · ReceiverVerify the deliveryAuthentication, environment and account
- 02 · StorageSave, then acknowledgeRetain the receipt and processing state
- 03 · WorkerApply the update onceMatch the record and current state
- 04 · ReconciliationRecover missing activityCheck the account or payment record
Verify the event and account
Validate the notification using its documentation and check the environment and merchant account. Do not use unsupported or uncertain data to change an order or account automatically.
Save work before acknowledging receipt
Durably record the receipt and the work needed to resume processing. Store only the necessary payload data with appropriate access and retention controls. Return the required acknowledgment after durable acceptance, within the subscription’s response window.
Apply the update once
Prevent duplicate deliveries from repeating fulfillment or a financial action. Use an atomic update with an identity that covers the environment, merchant, payment or operation, and state change. A transaction ID alone can include several legitimate updates.
Resolve delayed or conflicting updates
Check the current record before applying a delayed or conflicting event. Use the authorized lookup when necessary. A later arrival or a larger timestamp alone must not overwrite a confirmed outcome.
A retry has a different trace ID
Keep both delivery attempts for diagnostics, then match them to the same order or account update. If the update was already applied, acknowledge the delivery according to its documentation without repeating the action.
Two payments share a subscription
Keep both transactions. Deduplicating only by subscription identity would discard legitimate payments.
The worker stops after acknowledgment
Resume from the saved receipt and processing state. Apply the update atomically so a worker restart cannot repeat the action.
Acknowledgment confirms receipt of the notification. Payment completion is established separately by the verified payment record.
Match funding updates to deposit records
Funding notifications do not use the checkout payment status model. A funding instruction, a batch and an individual merchant deposit are different records. Read each result in its own account scope.
| Record | Next check |
|---|---|
| Instruction submission | Confirm whether the request was accepted, rejected or remains unresolved. Submission does not establish bank receipt. |
| Batch outcome | Inspect individual merchant deposits when only part of the batch completes. |
| Merchant deposit | Match the deposit to its merchant and report, then reconcile the receiving bank entry. |
Recover missing events and delivery failures
Record the retry policy and subscription health checks assigned to your connection. Do not assume a universal retry interval or that delivery will continue indefinitely. Reconcile against authoritative records when notifications stop or a result remains uncertain.
| Scenario | How to handle it |
|---|---|
| Invalid signature or encryption | No business record changes. Safe diagnostics identify the failed verification step. |
| Same payment, new retry trace | Retain the receipts needed for investigation; apply the order or account update only once. |
| Two payments, one subscription | Both legitimate transactions are processed. Subscription identity does not suppress the second payment. |
| Old result arrives last | An older event does not replace the confirmed current state. Resolve conflicting updates through the authoritative record. |
| Receipt storage fails | The receiver does not falsely acknowledge durable acceptance. Recovery follows the subscription instructions. |
| Worker interruption | After receipt is acknowledged, stored work resumes without repeating fulfillment or a financial operation. |
| Delivery stops | Subscription health, credentials and certificates are checked; missing activity is recovered through reconciliation. |
Capture useful diagnostics
Keep the environment, subscription ID, delivery attempt IDs, event type, receipt time, mapped merchant and affected record reference. Distinguish a delivery failure from a failure in the worker or in business validation. Do not put decrypted payment data, tokens or private keys into ordinary logs.