Event Handlers
Rafiki communicates with the Account Servicing Entity over webhook events, as mentioned in the Getting Started section. Most events require the Account Servicing Entity interact with Rafiki, either to deposit or withdraw liquidity into or from Rafiki, or to provide wallet address information. This document will describe how an Account Servicing Entity should handle each of the defined webhook events.
incoming_payment.created
The incoming_payment.created event indicates that an incoming payment has been created. It has not yet received any funds so no action is required. The webhook event is informational and allows the Account Servicing Entity to display upcoming incoming payments to their users.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: incoming payment created
ASE->>ASE: no action required
incoming_payment.completed
The incoming_payment.completed event indicates that an incoming payment has been completed, either automatically or manually, and that any funds that have been received into this incoming payment should be withdrawn and credited to the recipient’s account with the Account Servicing Entity.
Example: An incoming payment was completed and received $10.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: incoming payment completed,
receivedAmount: $10
ASE->>R: admin API call: WithdrawIncomingPaymentLiquidity
ASE->>ASE: credit receiver's account with $10
incoming_payment.expired
The incoming_payment.expired event indicates that an incoming payment has expired, and that any funds that have been received into this incoming payment should be withdrawn and credited to the recipient’s account with the Account Servicing Entity. Note that this event is not fired if there were no funds received by the incoming payment since there is no action required by the Account Servicing Entity.
Example: An incoming payment has expired and received $2.55.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: incoming payment expired,
receivedAmount: $2.55
ASE->>R: admin API call: WithdrawIncomingPaymentLiquidity
ASE->>ASE: credit receiver's account with $2.55
outgoing_payment.created
The outgoing_payment.created event indicates that an outgoing payment has been created and is awaiting liquidity. The Account Servicing Entity should put a hold on the sender’s account and deposit the funds into Rafiki.
Example: An outgoing payment for $12 has been created.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: outgoing payment created,
debitAmount: $12
ASE->>ASE: put hold of $12 on sender's account
ASE->>R: admin API call: DepositOutgoingPaymentLiquidity
outgoing_payment.completed
The outgoing_payment.completed event indicates that an outgoing payment has successfully sent as many funds as possible to the receiver. The Account Servicing Entity should withdraw any excess liquidity from that outgoing payment in Rafiki and use it as they see fit. One option would be to return it to the sender. Another option is that the excess liquidity is considered a fee and retained by the Account Servicing Entity. Furthermore, the Account Servicing Entity should remove the hold on the sender’s account and debit it.
Example: An outgoing payment for
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: outgoing completed,
debitAmount: $12, sentAmount:$11.50
ASE->>R: admin API call: WithdrawOutgoingPaymentLiquidity
ASE->>ASE: remove the hold and deduct $12 from the sender's account,
credit ASE's account with $0.50
outgoing_payment.failed
The outgoing_payment.failed event indicates that an outgoing payment has either partially or completely failed and a retry was also unsuccessful. The Account Servicing Entity should withdraw any remaining liquidity from that outgoing payment in Rafiki. If the payment failed completely (the sentAmount was 0), the Account Servicing Entity should remove the hold from the sender’s account. If the payment failed partially, the Account Servicing Entity should remove the hold from the sender’s account and debit it with the amount that has been sent, but they should refrain from taking a sending fee.
Example: An outgoing payment for
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: outgoing failed,
debitAmount: $12, sentAmount:$8
ASE->>R: admin API call: WithdrawOutgoingPaymentLiquidity
ASE->>ASE: remove the hold and deduct $8 from the sender's account
wallet_address.web_monetization
The wallet_address.web_monetization event indicates that a wallet address has received web monetization payments via STREAM (raw ILP access). The Account Servicing Entity should withdraw that liquidity from the wallet address and credit the receiver’s account.
Example: A wallet address received $0.33
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: wallet address web monetization,
receivedAmount: $0.33
ASE->>R: admin API call: CreateWalletAddressWithdrawal
ASE->>ASE: credit receiver's account with $0.33
wallet_address.not_found
The wallet_address.not_found event indicates that a wallet address was requested (via the Open Payments API), but it doesn’t exist in Rafiki. When receiving this event, the Account Servicing Entity can perform a lookup for the relevant account in their system, and create a wallet address. The initial request for the wallet address will succeed if the Account Servicing Entity creates it within the configurable WALLET_ADDRESS_LOOKUP_TIMEOUT_MS timeframe.
Example: The wallet address https://example-wallet.com/carla_garcia was requested but does not yet exist
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: wallet address not found,
wallet address: https://example-wallet.com/carla_garcia
ASE->>R: admin API call: CreateWalletAddress
url: https://example-wallet.com/carla_garcia,
public name: Carla Eva Garcia
asset.liquidity_low
The asset.liquidity_low event indicates that the liquidity of an asset has dropped below a predefined liquidity threshold. When receiving this event, the Account Servicing Entity should check if they have or can acquire additional liquidity of said asset and if so, deposit it in Rafiki. If the Account Servicing Entity cannot or does not increase the asset liquidity in Rafiki, cross-currency transfers will fail.
Example: The asset liquidity for USD (scale: 2) drops below 100.00 USD.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: liquidity (asset) low,
asset: USD (scale: 2, id: "abc")
ASE->>R: admin API call: DepositAssetLiquidity
peer.liquidity_low
The peer.liquidity_low event indicates that the liquidity of a peer has dropped below a predefined liquidity threshold. When receiving this event, the Account Servicing Entity need to decide if they can extend said peer’s credit line or whether they need to settle first and then extend a new line of credit. If the Account Servicing Entity cannot or does not increase the peer liquidity in Rafiki, transfers to that peer will fail.
Example: The peer liquidity for Happy Life Bank drops below 100.00 USD.
sequenceDiagram
participant ASE as Account Servicing Entity
participant R as Rafiki
R->>ASE: webhook event: liquidity (peer) low,
peer: Happy Life Bank (asset: "USD", scale: 2, id: "abc")
ASE->>R: admin API call: DepositPeerLiquidity