Transaction Monitoring

This document outlines the webhooks dispatched by the Transaction Monitoring & Fraud Prevention system. Webhooks are delivered to the organization's configured webhook_url to provide real-time updates on transaction screening statuses, risk escalations, and custom rule triggers.

Overview
All webhooks follow a standardized response envelope. The core data, including the event type and the transaction's screening results, is contained within the data object.

*Standard Payload Structure:

{  "status": true,  "detail": null,  "response_code": "00",  "data": {    "event": "<EVENT_TYPE>",    "screening_result": {      "transaction_id": "tx_12345",      "risk_score": 75,      "risk_level": "high",      "amount": "15000.00",      "status": "PENDING_REVIEW",      "rules_triggered": ["ff005685-b683-4273-b613-86acaf069256"],      "rules_triggered_details": [         {           "id": "ff005685-b683-4273-b613-86acaf069256",           "name": "High Amount Rule",           "severity": "high",           "description": "Flags transactions above standard threshold",           "risk_score_weight": 60         }      ]    }  }}

Event Types Summary
The event field in the payload indicates what triggered the webhook. The system currently supports three event types:

Detailed Event Payloads
There are three distinct webhook events dispatched by the system.

1. transaction.processed
   Trigger: Dispatched automatically for every transaction as soon as it has been successfully screened by the ML engine and custom rules engine. Use Case: Ideal for keeping an internal database in sync with Prembly's risk assessments or building a custom transaction dashboard.
   Example Payload:

{  "status": true,  "detail": null,  "response_code": "00",  "data": {    "event": "transaction.processed",    "screening_result": { ... }  }}

2. transaction.escalated
   Trigger: Dispatched when a transaction's final risk score or properties violate a globally configured Escalation Policy (e.g., "Alert on all transactions with Risk Score > 80"). Use Case: Used to trigger high-priority alerts for compliance teams or to automatically halt internal processes when a global risk threshold is breached.
   Additional Fields:
   escalation_rule: The name of the escalation policy that caught the transaction.

Example Payload:

{  "status": true,  "detail": null,  "response_code": "00",  "data": {    "event": "transaction.escalated",    "escalation_rule": "Critical Risk Escalation",    "screening_result": { ... }  }}

3. rule.triggered
   Trigger: Dispatched whenever a specific Custom Rule is triggered by a transaction, provided that the rule has send_alert enabled and Webhook notifications selected in its alert_channels. Use Case: Highly granular alerting. Allows product and risk teams to listen for specific behavioral anomalies (e.g., "Geo-Mismatch Rule") without subscribing to all escalated transactions.
   Additional Fields:
   rule_name: The name of the specific custom rule that was triggered.

Example Payload:

{  "status": true,  "detail": null,  "response_code": "00",  "data": {    "event": "rule.triggered",    "rule_name": "High Amount Rule (Test)",    "screening_result": { ... }  }}

Delivery Mechanism & Retries
Asynchronous Delivery: Webhooks are dispatched via background workers to ensure transaction screening API response times are not bottlenecked.
Headers: Payloads are sent with a standard Content-Type: application/json header.
Timeout: Delivery attempts have a strict 10-second timeout.