Advanced

Managing Alert Webhooks

Configure and use alert webhooks to receive risk alerts when Watch rules are triggered.

Alert webhooks let you send risk alerts to your own endpoints when one or more rules trigger for a transaction.

You configure webhook URLs and options with environment variables; Watch sends a POST request with the consolidated verdict, score, and evaluation data whenever the alert criteria are met.

How alert webhooks work

Enable alert webhooks by setting the webhook URL and turning delivery on in your .env file:

# Where to send alert payloads (required for delivery)
ALERT_WEBHOOK_URL=https://your-server.com/alerts

# Set to false to disable alert delivery; default is true
ALERT_WEBHOOK_ENABLED=true

Watch sends an alert webhook only when all of these conditions are met:

At least one rule triggered for the transaction during evaluation.
Alert webhooks are enabled - ALERT_WEBHOOK_ENABLED is not set to false.
Alert criteria are met - either:
- The consolidated risk score is greater than or equal to ALERT_WEBHOOK_RISK_THRESHOLD (default is 0.5), or
- The consolidated verdict is block or review.

If no webhook URLs are set, Watch skips delivery and does not retry.

Delivery behavior

Watch sends a POST request with Content-Type: application/json and the payload structure below.

If you set ALERT_WEBHOOK_API_KEY, Watch includes Authorization: Bearer <value> on each request. Your endpoint should return a 2xx status code to indicate success.

Webhook payload structure

Here’s the alert payload sent when a transaction triggers one or more rules:

{
  "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "description": "Transaction amount exceeds 10,000 in any currency.",
  "risk_level": "medium",
  "risk_score": 0.65,
  "verdict": "review",
  "source_count": 2,
  "evaluation_data": {
    "final_risk_score": 0.65,
    "final_verdict": "review",
    "final_reason": "Transaction amount exceeds 10,000 in any currency.",
    "source_count": 2,
    "transaction_amount": 15000,
    "transaction_reference": "ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "dsl_verdicts": [
      {
        "rule_id": 1,
        "name": "HighValueCheck",
        "verdict": "review",
        "score": 0.7,
        "reason": "Amount > 10000"
      },
      {
        "rule_id": 2,
        "name": "VelocityCheck",
        "verdict": "allow",
        "score": 0.1,
        "reason": ""
      }
    ]
  }
}

Field	Type	Description
`transaction_id`	string	ID of the transaction that was evaluated.
`description`	string	Human-readable description of the rule triggered; usually the consolidated reason.
`risk_level`	string	One of `very_low`, `low`, `medium`, `high` (derived from risk score).
`risk_score`	number	Consolidated risk score (0–1).
`verdict`	string	Consolidated verdict (e.g. `allow`, `review`, `block`).
`source_count`	integer	Number of rules that triggered for this transaction.
`evaluation_data`	object	Detailed evaluation output (see below).

The evaluation_data object contains:

Field	Type	Description
`final_risk_score`	number	Same as top-level `risk_score`.
`final_verdict`	string	Same as top-level `verdict`.
`final_reason`	string	Same as top-level `description`.
`source_count`	integer	Same as top-level `source_count`.
`transaction_amount`	number	Transaction amount.
`transaction_reference`	string	Transaction reference, if set.
`dsl_verdicts`	array	Per-rule verdicts when available. Each item includes `rule_id`, `name`, `verdict`, `score`, and `reason`.

Security considerations

Use HTTPS for all webhook URLs in production.
Set ALERT_WEBHOOK_API_KEY and validate the Authorization: Bearer <token> header in your endpoint to ensure requests are from Watch.
Do not log or store the API key in plain text.