Webhooks

Radom webhooks send JSON POST requests to your endpoint when important organization activity occurs. Use them to automate fulfillment, reconciliation, support workflows, customer notifications, and finance operations without polling the Dashboard.

Webhook payloads are event notifications. They should be treated as the source of truth for asynchronous state changes, but your handler should still be idempotent because delivery can be retried.

Payload model

Every webhook payload includes:

Field	Description
id	Unique webhook message ID. Use this for idempotency.
webhookId	The webhook endpoint that Radom attempted to deliver to.
eventType	The event name, such as managedPayment, refund, or payout.
eventData	Event-specific payload data. The property inside eventData matches eventType.
radomData	Related Radom object context, such as a checkout session, payment link, invoice, payment session, subscription, or donation link. This can be null for events that are not tied to one of those objects.

Event catalog

Event type	Use it for	Notes
managedPayment	Final successful one-time payments.	For open banking checkout sessions, this is still the final successful payment event.
managedRecurringPayment	Successful checkout payments that include subscription products.	New subscription records are sent separately as newSubscription events.
paymentTransactionDetected	Blockchain transaction detected for a payment.	Detection is not final confirmation.
paymentTransactionConfirmed	Blockchain transaction confirmed for a payment.	Use alongside final payment events for reconciliation.
managedWithdrawal	Withdrawal request completed successfully or failed.	Check the withdrawal payload for the outcome.
incompletePayment	Expired payments where less than the amount due was received.	Useful for support and reconciliation.
newSubscription	New subscription created.	Usually follows a checkout that included a subscription product.
subscriptionCancelled	Subscription cancelled.	Can be cancelled by the merchant or customer.
subscriptionExpired	Subscription expired after payment could not be collected.	Marks the end of the failed collection grace period.
subscriptionPayment	Subscription payment charged successfully.	Use to update billing state.
subscriptionPaymentAttemptFailure	Automated subscription payment attempt failed.	Can be caused by insufficient balance, allowance, or another payment failure.
subscriptionPaymentReminder	Subscription payment is upcoming.	Use for customer notification workflows.
subscriptionPaymentOverdue	Subscription payment is overdue.	Radom retries subscription payments during the grace period.
refund	Refund processed successfully or failed.	Check isSuccess and failureReason.
onramp	Onramp state changes.	Separate from checkout-session payment webhooks.
payout	Payout state changes.	Covers payout operations and entries exposed in the payout payload.
deposit	Deposit processed.	Use for deposit-account and treasury reconciliation workflows.
test	Manual endpoint connectivity checks.	Sent by the test webhook endpoint. It does not represent payment, subscription, deposit, payout, or refund activity.

Delivery behavior

Each active webhook endpoint receives matching event payloads in real time. If your endpoint does not return a successful 2xx response, Radom retries delivery up to 4 additional times, for up to 5 delivery attempts total.

You can inspect delivery history and manually retry failed messages from the Developer Webhooks page in the Dashboard.

Security

Validate the radom-verification-key request header against the verification key generated when you create the webhook endpoint. Reject requests with a missing or invalid verification key before processing the payload.

Start here

• Follow the webhook setup guide to register an endpoint, validate incoming messages, and process events safely.
• Browse the event pages in the sidebar for field-level payload schemas and examples.
• For open banking checkout sessions, use the final managedPayment webhook before fulfillment. The payload can include openBankingPaymentData with bank rail and final status details.