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.

Rillis uses webhooks to notify your system in real time when certain events occur. There are two types of webhook events:

Transaction Webhooks — Triggered when a transaction analysis is completed or its status changes.

Entity Analysis Webhooks — Triggered when a beneficiary or remitter analysis is completed.

1. Transaction Webhooks

Transaction webhooks are sent when a transaction's analysis is completed or its status changes. The payload is sent directly as the request body (no wrapper object).

Payload Schema

Field	Type	Description
`external_transaction_id`	`string`	Transaction ID assigned by your system.
`transaction_type`	`string`	Transaction type: `"FIAT"` or `"CRYPTO"`.
`sending_dollar_amount`	`number \| null`	Amount in US dollars.
`asset`	`string \| null`	Crypto asset symbol (e.g. `"USDT"`, `"BTC"`). `null` for fiat.
`sending_amount`	`number`	Amount sent by the sender in the sending currency.
`sending_currency`	`string`	Currency sent by the sender (e.g. `"CLP"`, `"USD"`).
`network`	`string \| null`	Blockchain network (e.g. `"Binance_Smart_Chain"`). `null` for fiat.
`sending_wallet`	`string \| null`	Sender's wallet address. `null` for fiat.
`receiving_amount`	`number`	Amount received by the beneficiary.
`receiving_currency`	`string \| null`	Currency received by the beneficiary.
`receiving_wallet`	`string \| null`	Beneficiary's wallet address. `null` for fiat.
`reasons_rejection_analysis`	`string \| null`	Rejection reason from the automated analysis.
`reasons_rejection_operator`	`string \| null`	Rejection reason specified by the operator.
`reasons_rejection_operator_list`	`string[] \| null`	List of rejection categories (e.g. `"BLACKLIST"`, `"SANCTION"`).
`rejected_at`	`number \| null`	Timestamp (ms) when the transaction was rejected.
`analyzed_at`	`number \| null`	Timestamp (ms) when the transaction was analyzed.
`risk_level`	`string \| null`	Risk level: `"HIGH"`, `"MEDIUM"`, `"LOW"`, or `null`.
`state`	`string`	Current state of the transaction (see states below).
`state_change_note`	`string \| null`	Note added by the operator when changing the state.
`remitter_limits`	`object \| null`	Remitter limit information, if applicable.
`beneficiary_limits`	`object \| null`	Beneficiary limit information, if applicable.

Transaction States

State	Description
`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`	The transaction was cancelled by the operator.

Example Payload

{
  "external_transaction_id": "AWCTTTTXXXX1191",
  "transaction_type": "CRYPTO",
  "sending_dollar_amount": 10,
  "asset": "USDT",
  "sending_amount": 3424342,
  "sending_currency": "CLP",
  "network": "Binance_Smart_Chain",
  "sending_wallet": null,
  "receiving_amount": 10,
  "receiving_currency": null,
  "receiving_wallet": "0x9707306916a4e8e8e9dfa1df6017b074e3b59a70",
  "reasons_rejection_analysis": "Se rechazo por coincidencia en listas de sanciones.",
  "reasons_rejection_operator": null,
  "reasons_rejection_operator_list": [
    "BLACKLIST",
    "SANCTION"
  ],
  "rejected_at": 1771014551436,
  "analyzed_at": 1771014551436,
  "risk_level": "HIGH",
  "state": "REJECTED",
  "state_change_note": "test",
  "remitter_limits": null,
  "beneficiary_limits": null
}

2. Entity Analysis Webhooks (Beneficiaries & Remitters)

Entity analysis webhooks are sent when the analysis of a beneficiary or remitter is completed. Both share the same payload structure. The only difference is the event_type field:

Event Type	Description
`ANALYSIS_BENEFICIARY`	Analysis of a beneficiary was completed.
`ANALYSIS_REMITTER`	Analysis of a remitter was completed.

Payload Structure

The payload is wrapped in a root object with three fields:

Field	Type	Description
`data`	`object`	The entity analysis result (see below).
`timestamp`	`number`	Timestamp (ms) when the webhook was sent.
`event_type`	`string`	`"ANALYSIS_BENEFICIARY"` or `"ANALYSIS_REMITTER"`.

`data` Object

Field	Type	Description
`id`	`string`	Internal Rillis ID of the entity.
`external_id`	`string`	Your unique identifier for this entity.
`entity_type`	`string`	Type of entity: `"CRYPTO"`, `"PERSON"`, or `"COMPANY"`.
`analyzed_at`	`number`	Timestamp (ms) when the analysis was completed.
`registered_in`	`number`	Timestamp (ms) when the entity was registered.
`status`	`string`	Final status: `"COMPLETED"` or `"REJECTED"`.
`has_coincidences`	`boolean`	`true` if matches were found in risk/sanction lists.
`has_risk_level`	`string \| null`	Detected risk level: `"HIGH"`, `"MEDIUM"`, `"LOW"`, or `null`.
`has_blacklist_matches`	`boolean`	`true` if matches were found in blacklists.
`has_deceased_matches`	`boolean`	`true` if matches were found in deceased person registries.
`crypto`	`object \| null`	Crypto analysis details. Present when `entity_type` is `"CRYPTO"`.
`natural_person`	`object \| null`	Person analysis details. Present when `entity_type` is `"PERSON"`.
`legal_person`	`object \| null`	Company analysis details. Present when `entity_type` is `"COMPANY"`.

Entity Statuses

Status	Description
`COMPLETED`	The entity was analyzed and approved.
`REJECTED`	The entity was analyzed and rejected due to risk.

Entity Type: CRYPTO

When entity_type is "CRYPTO", the crypto object contains:

Field	Type	Description
`address`	`string`	The blockchain wallet address.
`network`	`string`	Blockchain network (e.g. `"BITCOIN"`, `"ETHEREUM"`).
`asset`	`string`	Crypto asset (e.g. `"BTC"`, `"ETH"`, `"USDT"`).
`analysis`	`object \| null`	Detailed analysis result (see below).

`crypto.analysis` Key Fields

Field	Type	Description
`coincidences`	`boolean`	`true` if risk matches were found.
`status`	`string`	Analysis status (e.g. `"completed"`).
`risk_level`	`string \| null`	Risk level: `"HIGH"`, `"MEDIUM"`, `"LOW"`, or `null`.
`rejection_reasons`	`string \| null`	Reason for rejection, if applicable.
`rejected_at`	`number \| null`	Timestamp (ms) when the entity was rejected.
`analyzed_at`	`number`	Timestamp (ms) when the analysis was completed.
`alerts`	`array`	List of alerts found during analysis.
`directExposure`	`object \| null`	Direct exposure information if the address is directly identified.

`alerts` Array Items

Field	Type	Description
`alertLevel`	`string`	Alert severity: `"HIGH"`, `"MEDIUM"`, `"LOW"`.
`category`	`string`	Risk category (e.g. `"darknet market"`, `"sanctions"`).
`service`	`string`	Identified service name.
`alertAmount`	`number`	Dollar amount associated with the alert.
`exposureType`	`string`	Exposure type: `"DIRECT"` or `"INDIRECT"`.

Example: CRYPTO Entity (Beneficiary)

{
  "data": {
    "external_id": "test-crypto-PRD-javier-01",
    "analyzed_at": 1770999421063,
    "crypto": {
      "address": "bc1q8m4h4d92apd0s8jmwx9ywy6eamh9rl58n2a6sm",
      "network": "BITCOIN",
      "asset": "BTC",
      "analysis": {
        "coincidences": true,
        "status": "completed",
        "risk_level": "HIGH",
        "rejection_reasons": "Se rechazo por coincidencia en listas de sanciones.",
        "rejected_at": 1770999420759,
        "analyzed_at": 1770999420759,
        "alerts": [
          {
            "alertLevel": "HIGH",
            "category": "darknet market",
            "service": "Kraken Market",
            "alertAmount": 68632.44,
            "exposureType": "DIRECT"
          }
        ],
        "directExposure": {
          "direct": {
            "name": "Kraken Market",
            "category": "darknet market"
          }
        }
      }
    },
    "entity_type": "CRYPTO",
    "legal_person": null,
    "natural_person": null,
    "registered_in": 1770999391641,
    "has_coincidences": true,
    "has_risk_level": "HIGH",
    "has_blacklist_matches": false,
    "has_deceased_matches": false,
    "status": "REJECTED",
    "id": "698f4e5fa6b0642b2b57748b"
  },
  "timestamp": 1770999442302,
  "event_type": "ANALYSIS_BENEFICIARY"
}

Entity Type: PERSON

When entity_type is "PERSON", the natural_person object contains:

Field	Type	Description
`full_name`	`string`	Full name of the person.
`gender`	`string \| null`	Gender: `"MALE"`, `"FEMALE"`, or `null`.
`nationality`	`string \| null`	ISO 3166-1 alpha-3 country code of nationality.
`document_type`	`string \| null`	Document type (e.g. `"COL-CC"`, `"PER-DNI"`).
`document_number`	`string \| null`	Document number.
`issuer_country`	`string \| null`	ISO 3166-1 alpha-3 country code of the document issuer.
`phone`	`string \| null`	Phone number.
`email`	`string \| null`	Email address.
`address`	`string \| null`	Physical address.
`country`	`string \| null`	ISO 3166-1 alpha-3 country code of residence.
`date_of_birth`	`string \| null`	Date of birth.
`analysis`	`object \| null`	Detailed analysis result (see below).

`natural_person.analysis` Key Fields

Field	Type	Description
`coincidences`	`boolean`	`true` if risk matches were found.
`risk_level`	`string \| null`	Risk level: `"HIGH"`, `"MEDIUM"`, `"LOW"`, or `null`.
`rejection_reasons`	`string \| null`	Reason for rejection, if applicable.
`rejected_at`	`number \| null`	Timestamp (ms) when the entity was rejected.
`analyzed_at`	`number`	Timestamp (ms) when the analysis was completed.
`blacklistMatches`	`array`	List of blacklist matches found.
`deceasedListMatches`	`array`	List of deceased registry matches found.
`binding_list`	`object \| null`	Results from local government registry checks (country-specific).

`binding_list` Object

Field	Type	Description
`status`	`string`	Status of the binding list check: `"COMPLETED"` or `"PENDING"`.
`response`	`array`	Array of individual scraper/check results.
`scrapers_total`	`number`	Total number of scrapers executed.
`recommendations`	`array`	List of recommended actions based on the analysis.
`summary`	`object`	Aggregated risk summary.

`binding_list.summary` Object

Field	Type	Description
`risk_score`	`number`	Aggregated risk score (0–100).
`risk_level`	`string`	Overall risk level: `"HIGH"`, `"MEDIUM"`, `"LOW"`.
`confidence`	`string`	Confidence level: `"HIGH"`, `"MEDIUM"`, `"LOW"`.

`binding_list.response[]` Items

Each item represents a single registry check:

Field	Type	Description
`scraper`	`string`	Name of the scraper/registry checked.
`output`	`object`	Raw output from the registry.
`success`	`boolean`	Whether the check was executed successfully.
`results`	`object`	Interpreted results with `risk_score`, `risk_level`, `confidence`, and `notes`.
`passed`	`boolean`	`true` if the check passed (no risk found).
`completed_at`	`string`	ISO 8601 timestamp of when the check completed.

Example: PERSON Entity (Remitter)

{
  "data": {
    "external_id": "remitente-DEV-jesus-0029",
    "analyzed_at": 1770822894896,
    "crypto": null,
    "entity_type": "PERSON",
    "legal_person": null,
    "natural_person": {
      "full_name": "MIGUEL URIBE TURBAY",
      "gender": "MALE",
      "nationality": "COL",
      "document_type": "COL-CC",
      "document_number": "81717607",
      "issuer_country": "COL",
      "phone": null,
      "email": null,
      "address": null,
      "country": "COL",
      "date_of_birth": null,
      "analysis": {
        "coincidences": true,
        "risk_level": "HIGH",
        "rejection_reasons": "Se rechazo por coincidencia en listas de sanciones.",
        "rejected_at": 1770822600763,
        "analyzed_at": 1770822600763,
        "blacklistMatches": [],
        "deceasedListMatches": [
          {
            "full_name": "MIGUEL URIBE TURBAY",
            "entity_type": "PERSON",
            "identification_number": "81717607",
            "binding_list": true
          },
          {
            "isDeceased": true,
            "source": "binding_list",
            "match_percentage": 100
          }
        ],
        "binding_list": {
          "status": "COMPLETED",
          "scrapers_total": 4,
          "recommendations": [
            "Manual review requested due to SISBÉN portal maintenance.",
            "Investigate discrepancy in defunciones data.",
            "Proceed with standard risk processing given clean antecedents.",
            "Re-run SISBÉN data when portal is accessible."
          ],
          "summary": {
            "risk_score": 48,
            "risk_level": "MEDIUM",
            "confidence": "MEDIUM"
          }
        }
      }
    },
    "registered_in": 1770822599847,
    "has_coincidences": true,
    "has_risk_level": "HIGH",
    "has_blacklist_matches": false,
    "has_deceased_matches": true,
    "status": "REJECTED",
    "id": "698c9bc75fef4acf1ff1561b"
  },
  "timestamp": 1770822895873,
  "event_type": "ANALYSIS_REMITTER"
}

Entity Type: COMPANY

When entity_type is "COMPANY", the legal_person object contains the company details and analysis. The structure follows the same pattern as natural_person but with company-specific fields such as company name, registration number, and country of incorporation.

Quick Reference: Event Types

Event Type	Trigger	Payload Root
(Transaction)	Transaction status changes	Flat object
`ANALYSIS_BENEFICIARY`	Beneficiary entity analysis completed	`{ data, timestamp, event_type }`
`ANALYSIS_REMITTER`	Remitter entity analysis completed	`{ data, timestamp, event_type }`

Quick Reference: Statuses

Context	Possible Statuses
Transactions	`PROGRESS`, `COMPLETED`, `REJECTED`, `COMPLIANCE`, `EVALUATION`, `CANCELLED`
Entities	`COMPLETED`, `REJECTED`

Quick Reference: Risk Levels

Level	Description
`HIGH`	High risk — entity or transaction was flagged.
`MEDIUM`	Medium risk — review recommended.
`LOW`	Low risk — no significant issues found.

📤 Webhooks

Webhook Configuration#

1. Transaction Webhooks#

Payload Schema#

Transaction States#

Example Payload#

2. Entity Analysis Webhooks (Beneficiaries & Remitters)#

Payload Structure#

data Object#

Entity Statuses#

Entity Type: CRYPTO#

crypto.analysis Key Fields#

alerts Array Items#

Example: CRYPTO Entity (Beneficiary)#

Entity Type: PERSON#

natural_person.analysis Key Fields#

binding_list Object#

binding_list.summary Object#

binding_list.response[] Items#

Example: PERSON Entity (Remitter)#

Entity Type: COMPANY#

Quick Reference: Event Types#

Quick Reference: Statuses#

Quick Reference: Risk Levels#