Asynchronous API Operations through Webhooks
For processing asynchronous messages, Radial supports two flavors of integration: an AMQPS-based integration that uses the pull strategy and an HTTPS-based integration that uses the push strategy. Depending on the needs of your integration, you can choose to use either the push or the pull strategy. The push integration is an event callback (webhooks) framework that notifies clients when event messages are produced in Radial's internal systems.
Each store implementation can use only one of these integration strategies, push or pull, but not both.
Webhook Integration Flow
The sequence diagram below covers the system interactions in Webhooks integration:
Webhooks Notification (Push Strategy): For clients that prefer to be notified of the events, a Webhooks listener subscribes to the RabbitMQ queue. As soon as the message shows up on the AMQP endpoint, the webhooks service pulls down the message and submits it to the URLs registered for your store. The client at the registered URL is expected to acknowledge the message receipt with an HTTP 200 status response. As soon as the acknowledgment is received, the message is removed from the RabbitMQ queue.
Error Flow: If the client's URL is down or the service receives a 400 or 500 error (a non-2xx response), then an error alert is produced and the message is flagged for a retry. A retry job then periodically retries to submit the message to the client URL, until the max duration is reached. If the client acknowledges the message during the retry period, then the message is removed from the queue. If client endpoint is down after max retry duration, the service stops retrying and alerts Radial team to reach out to the customer and confirm the endpoint status.
Configuration
By default, each store is set up with RabbitMQ queues. However, as you prefer to integrate using the Webhooks option for asynchronous messages, you must associate an https endpoint to each of the RabbitMQ queues from which you want to receive messages. Radial's payment portal application provides an interface where you can view the queue names set up for your store and register an https endpoint (and user credentials, which are needed for the POST HTTP/HTTPS call).
Radial production environments require HTTPS URLs. In non-production environments, both HTTP and HTTPS can be used.
The Radial webhook sends authentication information using HTTP Basic Authentication. The configuration is typically done through Radial's Customer Portal. After registering as a user in Radial's Customer Portal, you can configure a client URL, username, and password for a given route.
If you need to whitelist the IP ranges from where Radial webhook calls originate:
- Radial non-production webhook origination IP ranges are 199.241.232.0/21
- Radial production webhook origination IP ranges are 104.192.196.0/22 and 206.16.220.0/23
Retries
The Webhooks retry job, which tries to push the response messages, runs frequently based on the configuration at Radial's end. Currently, it is setup to 1 minute and the job attempts to run every minute if the previous execution completes within the minute. If not, execution starts the following minute. If there is a failure at a specific endpoint, the job retries at time intervals that increase exponentially.
Message Format
The event messages posted to the HTTPS endpoints are slightly different from the messages that reside on the RabbitMQ. The messages that get posted back are consolidated into a list schema to prevent chattiness in the HTTPS callbacks. For details of the list schemas, see Payment Settlement Status List Event, Payment Authorization Cancel List Event, and Risk Assessment List Event.
These list events support a maximum of 50 responses in each message. If there are more than 50 items, multiple messages will be posted to the client-provided endpoint.