Webhooks
Receive real-time notifications when events occur in your Floodlight AML account.
Overview
Webhooks allow your application to receive HTTP POST callbacks when specific events occur. Instead of polling the API, you can subscribe to events and receive instant notifications.
Getting Started
Configure webhooks in your Dashboard under Settings → Webhooks. You'll need to provide a URL that can receive POST requests.
Event Types
| Event | Description | Payload |
|---|---|---|
| aml.alert.created | Triggered when a new alert is generated | alert object |
| aml.alert.updated | Triggered when alert status or details change | alert object |
| aml.transaction.screened | Triggered when a transaction screening completes | screening result |
| aml.transaction.ingested | Triggered when a transaction is ingested | transaction object |
| aml.sar.filed | Triggered when a SAR is successfully filed | sar object |
| aml.case.updated | Triggered when a case status or assignment changes | case object |
| aml.signal.emitted | Triggered when a risk signal is emitted | signal object |
Webhook Payload
All webhook payloads follow a consistent structure:
JSON
{
"event": "aml.transaction.screened",
"timestamp": "2026-04-14T12:00:05Z",
"tenantId": "your-tenant-id",
"data": {
"searchId": "srch_a1b2c3",
"query": {
"name": "Wei Zhang",
"alias": null,
"threshold": 75.0
},
"totalMatches": 2,
"truncated": false,
"matches": [
{
"matchId": "match_001",
"matchedName": "Wei Zhang",
"score": {
"overall": 94.0,
"algorithm": "BALANCED"
},
"sources": [
{
"type": "SANCTION_LIST",
"authority": "EU Sanctions List",
"referenceId": "eu-sdn-54321",
"publisher": "European Union",
"publishedDate": "2024-06-01"
}
],
"entity": {
"type": "INDIVIDUAL",
"nationality": "CN"
}
},
{
"matchId": "match_002",
"matchedName": "Wei Zhang",
"score": {
"overall": 65.0,
"algorithm": "BALANCED"
},
"sources": [
{
"type": "ADVERSE_MEDIA",
"authority": "Media Monitoring Service",
"referenceId": "media-ref-54321",
"publishedDate": "2026-03-22",
"url": "https://example.com/article",
"sentiment": "NEGATIVE"
}
],
"entity": {
"type": "INDIVIDUAL"
}
}
],
"screenedAt": "2026-04-14T12:00:01Z"
}
}Receiving Webhooks
Webhooks are delivered as HTTP POST requests to your configured endpoint URL. Your endpoint should return a 200 OK or 202 Accepted status to acknowledge receipt. Any non-2xx response will trigger a retry.
Retry Logic
If your endpoint fails to respond (returns non-2xx status), FloodLight will retry the webhook delivery with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
After 5 failed attempts, the webhook is moved to a dead letter queue.
Event Payload Examples
aml.alert.created
JSON
{
"event": "aml.alert.created",
"timestamp": "2026-04-14T12:00:00Z",
"tenantId": "your-tenant-id",
"data": {
"alertId": "alert-001",
"type": "PEP_SCREENING",
"severity": "HIGH",
"status": "DETECTED",
"customerId": "prof-001",
"customerName": "John Smith",
"riskScore": 75.0,
"riskLevel": "HIGH",
"description": "Individual matched against PEP database",
"reason": "PEP_MATCH",
"ruleCodes": "PEP_MATCH,HIGH_RISK_SCORE",
"createdAt": "2026-04-14T12:00:00Z",
"updatedAt": "2026-04-14T12:00:00Z"
}
}aml.transaction.screened
JSON
{
"event": "aml.transaction.screened",
"timestamp": "2026-04-14T12:00:01Z",
"tenantId": "your-tenant-id",
"data": {
"searchId": "srch_a1b2c3",
"query": {
"name": "John Smith",
"alias": null,
"threshold": 75.0
},
"totalMatches": 1,
"truncated": false,
"matches": [
{
"matchId": "match_001",
"matchedName": "John Smith",
"score": {
"overall": 94.0,
"nameScore": 100.0,
"idScore": null,
"dobScore": 100.0,
"nationalityScore": null,
"algorithm": "BALANCED"
},
"sources": [
{
"type": "PEP_LIST",
"authority": "Global PEP Registry",
"program": "pep_database",
"referenceId": "pep-ref-67890",
"publishedDate": "2025-06-01"
}
],
"entity": {
"type": "INDIVIDUAL",
"nationality": "US",
"dateOfBirth": "1985-03-15"
}
}
],
"screenedAt": "2026-04-14T12:00:01Z"
}
}Idempotency
Webhooks may be delivered multiple times. Always check the event ID or use idempotency keys to avoid processing the same event twice.