Transaction Monitoring & Fraud Prevention Webhooks

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.