Webhook events

The main communication channel between an FSP and their Rhyza instance consists of the Admin API and webhook events sent by the notifications service.

Note

Rhyza doesn’t hold account balances for an FSP’s users/customers. Instead, it tracks the liquidity of the FSP’s internal peer accounts in its own database.

Specify a webhook endpoint

For Rhyza to notify an FSP about webhook events, the FSP must expose a webhook endpoint that listens for the dispatched events. The events provide time-sensitive status updates, warnings, and errors so that the FSP can react accordingly.

The webhook endpoint URL is configured using the WEBHOOK_URL environment variable.

When an event occurs, the notifications service makes request to the configured endpoint. The service expects a 200 status in return.

Variable	Type	Description
WEBHOOK_URL	notifications	The endpoint where requests are made when a webhook event occurs.

Webhook event request body

Each webhook event is sent as a JSON payload with the following structure in the request body. The parameters in the data object vary depending on the event.

Attribute	Type	Description	Required
id	String	UUID for the event	Y
type	Enum	The event type	Y
data	Object	Additional data that coincides with the event type	Y

Duplicate events

The id in the webhook event payload is unique. An FSP can use the ID to determine whether the event was previously received, preventing duplicate event processing.

We provide an OpenAPI specification for the webhook events fired by Rhyza.

Additionally, the Local Playground contains example payloads in the Bruno collection that can be used to test an FSP’s webhook service integration.

Event handling

Asynchronous handling

If requests to credit or debit user accounts are lengthy processes, we recommend using a worker to process received events. The worker allows the server to process events at a rate suitable for the FPS’s system and reduces the number of failed/retried events since the event listener can immediately reply with a successful 200 status.

Error handling

Rhyza retries the webhook request at increasing intervals if the request times out or if a non-200 status is returned, indicating an error. The first retry occurs after 10 seconds. Additional retries occur after 20 more seconds, then after 30 more seconds, and so on. Rhyza continues to retry until a 200 status is returned.

FSPs can fine-tune timeouts and maximum retries by configuring the environment variables listed below.

Variable	Type	Description
WEBHOOK_TIMEOUT	notifications	The time, in milliseconds, after which a webhook request times out
WEBHOOK_MAX_RETRY	notifications	The maximum number of retries for a webhook event when a non-200 status is returned or if the request timed out