📤 Webhooks

Webhook Configuration

The URL must accept POST type requests

To receive notifications about changes in transaction statuses, you must configure this endpoint in your system and add the corresponding URL on the Rillis web platform. This way, you'll be ready to receive notifications whenever a transaction's status changes.

Webhook Payload Schema

When a transaction status changes, Rillis will send a POST request to your configured webhook URL with the following payload:

Parameter	Type	Description
client_transaction_id	String	Transaction ID, assigned by the querying company.
transaction_type	String	Transaction type: "fiat" or "crypto"
crypto_network	String or null	Type of cryptocurrency network. Example: "Cardano".
crypto_asset	String or null	Type of asset. Example: "ADA".
sending_dollar_amount	Number or null	Amount in dollars.
sending_amount	Number	Amount to be sent by the sender.
sending_currency	String	Currency to be sent by the sender.
sending_wallet	String or null	Sender's wallet address.
receiving_amount	Number	Amount received by the beneficiary.
receiving_currency	String	Currency received by the beneficiary.
receiving_wallet	String or null	Beneficiary's wallet address.
reasons_rejection_analysis	String or null	Rejection reason specified by the analysis.
reasons_rejection_operator	String or null	Rejection reason specified by the operator.
rejected_at	Number (timestamp) or null	Timestamp when the transaction was rejected.
analyzed_at	Number (timestamp) or null	Timestamp when the transaction was analyzed.
state	String	Current state of the transaction.

Transaction States

The state parameter can have the following values:

PROGRESS: The transaction is currently under analysis.

COMPLETED: The transaction has been analyzed and approved.

REJECTED: The transaction has been rejected during analysis.

COMPLIANCE: The client exceeded the threshold previously set by the company.

EVALUATION: Operator verification of the analysis is required.

CANCELLED: Transaction cancelled by the operator.

Example Webhook Payload

A webhook notification will contain the following JSON payload:

{
  "client_transaction_id": "1616",
  "transaction_type": "fiat",
  "sending_dollar_amount": 20,
  "crypto_asset": null,
  "sending_amount": 268,
  "sending_currency": "CLP",
  "crypto_network": null,
  "sending_wallet": null,
  "receiving_amount": 100,
  "receiving_currency": "USD",
  "receiving_wallet": null,
  "reasons_rejection_analysis": null,
  "reasons_rejection_operator": null,
  "rejected_at": null,
  "analyzed_at": 1684356854091,
  "state": "COMPLETED"
}

Webhook Response Requirements

Your webhook endpoint should respond with a 200 HTTP status code to acknowledge receipt of the notification. If Rillis does not receive a 200 response, it will retry sending the notification according to the following schedule:

1st retry: 5 minutes after the initial attempt

2nd retry: 15 minutes after the initial attempt

3rd retry: 30 minutes after the initial attempt

4th retry: 1 hour after the initial attempt

5th retry: 3 hours after the initial attempt

After the 5th retry, Rillis will stop attempting to send the notification.

Best Practices

Idempotency: Implement your webhook handler to be idempotent, as you may receive the same notification multiple times.

Verification: Consider implementing a verification mechanism to ensure the webhook is coming from Rillis.

Logging: Log all received webhooks for debugging and auditing purposes.

Async Processing: Process webhooks asynchronously to avoid timeouts.

Error Handling: Implement proper error handling to ensure your webhook endpoint can handle unexpected data.

📤 Webhooks

Webhook Configuration#

Webhook Payload Schema#

Transaction States#

Example Webhook Payload#