AML Monitor Update Webhook

Overview

This webhook is triggered whenever an AML match is updated as part of Ongoing Monitoring. Updates may include newly added matches, removed entries, or updates to match risk details.

The webhook allows you to react in real-time to any changes in an individual's AML screening status without needing to poll the system.

📘
Use case:
Ideal for compliance teams to receive instant alerts when an individual's AML profile changes post-onboarding due to new sanctions, watchlists, or PEP updates.

Payload

The IDWise backend will send a JSON HTTP POST request to the webhook configured, with the following details:

{  
  "event": "AML Monitor Update",  
  "body": {
    "eventId":"4****-****-****-*********7", 
    "journeyId": "6720***********22e",
    "referenceNo": "840...........23",
    "systemDecision": "<SYSTEM_DECISION>",
    "previousSystemDecision": "<PREVIOUS_SYSTEM_DECISION>",
    "updatedAMLVersionNumber": 1
    
  }  
}

📘
Note
Please note this object might be extended with extra elements. Ensure your code can accommodate any extra elements introduced to this payload object.

The JSON object provided contains information about certain events in the ID verification process. Here is the explanation of its elements:

event: Identifies the type of event that triggered this webhook. For AML monitor update webhook this will always be AML Monitor Update.

Inside the body element you find these elements:

eventId: A unique identifier to identify this event instance. Should the event be attempted again, the eventId will consistently remain unchanged throughout all retry attempts.
journeyId: A unique identifier for the journey, a specific instance of the verification process.
referenceNo: The reference number associated with the journey.
systemDecision: The automated decision by the IDWise system based on the inputs received.
previousSystemDecision: the journey system decision before the the AML update.
updatedAMLVersionNumber: An integer representing the version of the AML status update. This value increments by 1 with each ongoing monitoring update for this applicant. you can use this version to fetch the updated matches by this API.

How to Fetch the Updated AML Matches

To retrieve the latest changes in AML matches, use the AML History API, which fetches only the changes specific to that version (use updatedAMLVersionNumber from the payload).

AI integration prompt

Use this prompt with your AI coding assistant to generate an AML Monitor Update Webhook handler for your backend stack. The generated handler should acknowledge IDWise quickly, then asynchronously fetch the updated AML changes for the version included in the webhook payload.

Copy this prompt into your AI coding assistant to generate a backend webhook handler for AML ongoing monitoring updates.

View Integration Prompt

You are an expert backend engineer integrating the IDWise AML Monitor Update Webhook.

Before writing any code, ask me which backend stack, language, and framework I am using. Examples: Node.js with Express, Python with FastAPI, Python with Django, C# with ASP.NET, Java with Spring Boot, PHP with Laravel, Ruby on Rails, or another stack.

After I answer, generate a complete webhook handler for that stack.

This webhook means an AML match changed as part of Ongoing Monitoring. Updates may include newly added matches, removed entries, or updates to match risk details. The handler should use updatedAMLVersionNumber to fetch the AML changes for that specific monitoring update.

The webhook handler must:

1. Expose an HTTP POST endpoint that receives the IDWise AML Monitor Update webhook payload.
2. Parse the JSON payload without failing if IDWise adds extra fields in the future.
3. Read these fields from the payload:
   - event
   - body.eventId
   - body.journeyId
   - body.referenceNo
   - body.systemDecision
   - body.previousSystemDecision
   - body.updatedAMLVersionNumber
4. Validate that the event value is AML Monitor Update before processing the payload.
5. Validate that updatedAMLVersionNumber is present and is an integer.
6. Log that the AML Monitor Update webhook was triggered, including:
   - eventId
   - journeyId
   - referenceNo
   - previousSystemDecision
   - systemDecision
   - updatedAMLVersionNumber
7. Use eventId as an idempotency key so duplicate delivery attempts do not fetch or apply the same AML update more than once.
8. Return HTTP 200 to IDWise as soon as the payload is accepted and basic validation is complete.
9. Do not fetch AML history, fetch AML results, update the customer system, notify compliance teams, or trigger risk workflows before returning HTTP 200.
10. After returning HTTP 200, invoke an asynchronous method or background job named processAMLMonitorUpdate or an equivalent name for the selected stack.
11. In the asynchronous method, use journeyId and updatedAMLVersionNumber to call the IDWise AML History API and fetch only the AML changes for that version.
12. Use the fetched AML changes to update the customer system, create or update compliance alerts, and record an audit log.
13. If needed, fetch the full AML result after processing the version-specific AML history changes.
14. Add error handling and logging inside the asynchronous method so processing failures are recorded without causing IDWise webhook delivery to time out.
15. Keep IDWise API credentials out of source code by using environment variables or the stack's secret-management approach.

Return:

1. A short implementation checklist.
2. Complete runnable webhook handler code for the selected stack.
3. The asynchronous processAMLMonitorUpdate method or background job code.
4. Required environment variables.
5. Example log output for a successful webhook trigger, including journeyId, referenceNo, previousSystemDecision, systemDecision, and updatedAMLVersionNumber.
6. Notes explaining why the handler returns HTTP 200 before fetching AML history or updating the customer system.
7. Notes explaining how updatedAMLVersionNumber is used to fetch only the AML changes for this monitoring update.

Do not build this as a frontend handler. The webhook endpoint must run on a trusted backend.