--- title: "Watchlist-screening webhook | Veriff.com" slug: "watchlist-screening-webhook" description: "Set up Veriff's watchlist-screening webhook for PEP, Sanctions, and adverse media checks to get verification results and monitor changes in status." updated: 2026-07-08T15:38:11Z published: 2026-07-08T15:38:11Z canonical: "devdocs.veriff.com/watchlist-screening-webhook" --- > ## Documentation Index > Fetch the complete documentation index at: https://devdocs.veriff.com/llms.txt > Use this file to discover all available pages before exploring further. # Watchlist-screening webhook This webhook returns data from [Veriff PEP and Sanctions, adverse media (AM) checks and ongoing monitoring (OGM) services](/v1/docs/aml-screening-solution). The payload is sent to `Webhook watchlist screening URL`, which you need to set up the webhook in the Veriff Customer Portal. → *See Webhooks Guide > [Set up webhooks](https://veriff-dev-documentation.document360.io/docs/webhooks-guide#set-up-webhooks) sub-section for detailed overview of the setup process* #### In a nutshell: how AML Screening works If you landed here first, here is the full picture before you dig into the payload details: 1. Veriff runs the PEP, Sanctions, and Adverse Media check using your integration's configuration. If you are using an IDV integration (document or document+selfie), Veriff also runs the identity verification checks and sends that result via a separate decision webhook, alongside this one. See [AML Screening (enhanced)](/v1/docs/aml-screening-solution) for the full flow. 2. Results are delivered to you via this webhook, or you can poll them via the [GET /sessions/{sessionId}/watchlist-screening](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidwatchlist-screening-1) endpoint. The `reviewStatus` field tells you whether the person was found, and whether all hits have been reviewed. See the [About reviewStatus field](/v1/docs/aml-screening-solution#the-reviewstatus-field) section in AML Screening (enhanced) for more info. 3. If `reviewStatus` is `potential_match`, you review each hit and record your decision using the [PATCH /sessions/{sessionId}/watchlist-screening](/v1-api/apidocs/v1sessionsidwatchlist-screening) endpoint. See [Managing screening results](/v1/docs/aml-screening-solution#managing-screening-results1) in the AML Screening (enhanced) for the request format. 4. If ongoing monitoring is enabled, Veriff periodically re-checks the person and sends a new webhook if anything changes, this can reset `reviewStatus` back to `potential_match` until you acknowledge the change. --- ## When is watchlist-screening webhook sent? The webhook is sent after the PEP and Sanctions, adverse media and OGM checks have been passed. Note that a **new webhook** will be sent if the system detects that the **person's status in the database has changed**. A webhook is also sent when `reviewStatus` changes from `potential_match` to `reviewed`, that is, once you have submitted a review decision for every hit and acknowledged any pending monitoring changes. See "Managing screening results" in the [AML Screening (enhanced)](/v1/docs/aml-screening-solution) or [AML Screening (legacy)](/v1/docs/aml-screening) guide. --- ## Prerequisites 1. Make sure you **have access to the Veriff Customer Portal** 1. If you do not, see the Getting Started → [Sign up](https://devdocs.veriff.com/docs/signing-up) and [Log in](https://devdocs.veriff.com/docs/logging-in) articles 2. Set up webhook URL(s) **on your side** and have them at hand 1. Make sure they **match** the [Webhook URL](https://devdocs.veriff.com/docs/webhooks-guide#webhook-url-requirements) requirements 2. Make sure your system is **able to handle** [Webhooks receipt, delivery and resending](https://devdocs.veriff.com/docs/webhooks-guide#webhook-delivery-receipt-and-resending) requirements 3. Check the [Webhooks headers and payload](https://devdocs.veriff.com/docs/webhooks-guide#webhooks-headers-and-payload) section for info 3. Secure your communication, check the [HMAC Authentication and Endpoint Security](https://devdocs.veriff.com/docs/hmac-authentication-and-endpoint-security) article 4. Make sure your system is **able to handle** the [Backwards compatible changes](https://devdocs.veriff.com/docs/backwards-compatible-changes) 1. Proceed to [Watchlist-screening webhook setup](/v1/docs/watchlist-screening-webhook#watchlistscreening-webhook-setup) below --- ## Watchlist-screening webhook setup 1. Log in to the **Veriff Customer Portal** 2. Navigate to the **Integrations** page via the top menu and open the integration used for the AML solution 3. On the integration's page, select the **Settings** tab 4. Under the title **Integration settings** you see a list of webhooks 5. Fill in the `Webhook watchlist screening URL` → *See Webhooks Guide > [Set up webhooks](https://veriff-dev-documentation.document360.io/docs/webhooks-guide#set-up-webhooks) sub-section for detailed overview of the setup process* --- ## Additional notes String `reviewStatus` shows the overall review state of the screening result: - `no_match` indicates that the person was not found. The `hits` array is empty - `potential_match` indicates that one or more hits exist that have not yet been fully reviewed - `reviewed` indicates that all hits have been reviewed Note: The `matchStatus` field at the top level of the payload is deprecated. Use `reviewStatus` instead. `reviewed` is not a permanent state. If ongoing monitoring later detects a change, `hasUnacknowledgedChanges` becomes `true` and `reviewStatus` reverts to `potential_match`, even if every hit had already been reviewed. See "Managing screening results" in the [AML Screening (enhanced)](/v1/docs/aml-screening-solution) or [AML Screening (legacy)](/v1/docs/aml-screening) guide for how to acknowledge changes and review new hits. --- ## Sample request > [!NOTE] > The examples below use **placeholder data** to show the mandatory parameters and possible fields for this webhook. Your production payload will contain real screening data for the verified end-user, not these placeholder values. > > Some fields may be empty or missing: the `hits` array is empty when no matches are found, and the `lists`, `countries`, `exactMatch`, `matchThreshold`, and `excludeDeceased` keys inside `searchTerm` only appear for the enhanced AML solution, not legacy. ***Click to open a sample showing initial result, no match found*** ```json {    "checkType": "initial_result",    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",    "vendorData": "customer_ref_12345",    "endUserId": "c1de400b-1877-4284-8494-071d37916197",    "matchStatus": "no_match",    "reviewStatus": "no_match",    "hasUnacknowledgedChanges": false,    "monitorStatus": "enabled",    "searchTerm": {        "name": "John Smith",        "year": "1985",        "lists": [          "SANCTIONS",          "PEP_CLASS_1"        ],        "countries": [          "US"        ],        "exactMatch": false,        "matchThreshold": 80,        "excludeDeceased": true    },    "totalHits": 0,    "createdAt": "2021-07-05T13:23:59.851Z",    "hits": [] } ``` ***Click to open a sample showing initial result, match found*** ```json {    "checkType": "initial_result",    "attemptId": "54233318-f81c-4ec4-8e4c-413168a3f5e6",    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",    "vendorData": "12345678",    "endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4",    "matchStatus": "possible_match",    "reviewStatus": "potential_match",    "hasUnacknowledgedChanges": false,    "monitorStatus": "enabled",    "searchTerm": {        "name": "Mirko Kokki",        "year": "1960",        "lists": [          "SANCTIONS",          "PEP_CLASS_1",          "PEP_CLASS_2"        ],        "countries": [          "GB",          "US",          "FR"        ],        "exactMatch": false,        "matchThreshold": 80,        "excludeDeceased": true    },    "totalHits": 5,    "createdAt": "2021-06-02T11:04:00.287Z",    "hits": [{        "id": "4KJL9THDX9ZNV4W",        "matchStatus": "potential_match",        "matchedName": "Miro kokkino",        "countries": [          "Australia",          "Brazil"        ],        "dateOfBirth": "1960",        "dateOfDeath": null,        "matchTypes": [          "aka_exact"        ],        "aka": [          "Kokki Mirko",          "Mirko Kokki"        ],        "associates": [          "Desmon Lamela",          "Fred Austin"        ],        "listingsRelatedToMatch": {            "warnings": [            {                "sourceName": "FBI Most Wanted",                "sourceUrl": "http://www.exampleUrl.com",                "date": null            }            ],            "sanctions": [            {                "sourceName": "Example Source",                "sourceUrl": "https://www.exampleURL2.com",                "date": null            },            {                "sourceName": "Example Source 2",                "sourceUrl": "https://www.exampleURL3.com",                "date": null            }            ],            "fitnessProbity": [            {              "sourceName": "Example Source 3",              "sourceUrl": "https://www.exampleURL4.com"            }            ],            "pep": [            {              "sourceName": "Example Source 4",              "sourceUrl": "https://www.exampleURL5.com"            }            ],            "adverseMedia": [            {              "date": "2020-09-23T00:00:00Z",              "sourceName": "Example Source 5",              "snippet": "Sang Tan Judges in the High Court in London have ruled that Saleh Ibrahim Mabrouk, a former aide of Libyan leader Colonel Muammar Gaddafi, was partly to blame for the murder of PC Yvonne Fletcher. The gunman",              "sourceUrl": "https://www.exampleURL6.com"            }            ]        }    }    ]  } ``` ***Click to open a sample showing monitoring update payload*** Sent when ongoing monitoring detects a change in the person's status. `checkType` is `updated_result` and `hasUnacknowledgedChanges` is `true`. ```json {    "checkType": "updated_result",    "attemptId": "aea9ba6d-1b47-47fc-a4fc-f72b6d3584a7",    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",    "vendorData": "customer_ref_12345",    "endUserId": "c1de400b-1877-4284-8494-071d37916197",    "matchStatus": "possible_match",    "reviewStatus": "potential_match",    "hasUnacknowledgedChanges": true,    "monitorStatus": "enabled",    "searchTerm": {        "name": "Maria Santos",        "year": "1978",        "lists": [          "SANCTIONS",          "PEP_CLASS_1",          "PEP_CLASS_2"        ],        "countries": [          "BR",          "US"        ],        "exactMatch": false,        "matchThreshold": 80,        "excludeDeceased": false    },    "totalHits": 1,    "createdAt": "2021-07-15T08:45:22.123Z",    "hits": [{        "id": "7RMP2WNBY3KHQ8F",        "matchStatus": "potential_match",        "matchedName": "Maria Santos Silva",        "countries": [          "Brazil"        ],        "dateOfBirth": "1978",        "dateOfDeath": null,        "matchTypes": [          "matching_name",          "year_of_birth"        ],        "aka": [          "Maria S. Silva"        ],        "associates": [],        "listingsRelatedToMatch": {            "warnings": [],            "sanctions": [],            "fitnessProbity": [],            "pep": [            {                "sourceName": "Brazil Government Officials Database",                "sourceUrl": null,                "date": "2021-07-14"            }            ],            "adverseMedia": [            {                "sourceName": "Local News Reports",                "snippet": "Brazilian government official Maria Santos Silva appeared on a regional PEP watchlist following appointment to a federal oversight committee.",                "sourceUrl": null,                "date": "2021-07-10"            }            ]        }    }] } ``` ***Click to open a sample showing a “reviewed”* *case*** ```json {    "checkType": "updated_result",    "attemptId": "9f3c2e71-6b84-4a2f-8e2a-3c1f7e5d9b0a",    "sessionId": "f04bdb47-d3be-4b28-b028-a652feb060b5",    "vendorData": "customer_ref_67890",    "endUserId": "d2e510c6-2988-4395-9a15-7c3f28a37b62",    "matchStatus": "possible_match",    "reviewStatus": "reviewed",    "hasUnacknowledgedChanges": false,    "monitorStatus": "enabled",    "searchTerm": {        "name": "Mirko Kokki",        "year": "1960",        "lists": [          "SANCTIONS",          "PEP_CLASS_1"        ],        "countries": [          "GB"        ],        "exactMatch": false,        "matchThreshold": 80,        "excludeDeceased": true    },    "totalHits": 1,    "createdAt": "2021-06-05T09:12:41.502Z",    "hits": [{        "id": "4KJL9THDX9ZNV4W",        "matchStatus": "true_match",        "riskLevel": "high",        "matchedName": "Miro Kokkino",        "countries": ["Australia"],        "dateOfBirth": "1960",        "dateOfDeath": null,        "matchTypes": ["aka_exact"],        "aka": ["Kokki Mirko", "Mirko Kokki"],        "associates": ["Desmon Lamela"],        "listingsRelatedToMatch": {            "warnings": [],            "sanctions": [{                "sourceName": "Example Source",                "sourceUrl": "https://www.exampleURL2.com",                "date": null            }],            "fitnessProbity": [],            "pep": [],            "adverseMedia": []        }    }] } ``` ## Request properties - `checkType`: `string` Indicates the succession of the check, one of `initial_result`, `updated_result` - `attemptId`: `string` UUID v4 which identifies session attempt - `sessionId`: `string` UUID v4 which identifies session - `vendorData`: `string | null` The unique identifier that you created for your end-user - `endUserId`: `string | null` The `UUID` that you created for your end-user - `matchStatus`: `string` **Deprecated.** Use `reviewStatus` instead. Indicates if there was a match in the database, one of `possible_match`, `no_match` - `reviewStatus`: `string` Overall review state of the screening result, one of `no_match`, `potential_match`, `reviewed` - `hasUnacknowledgedChanges`: `boolean` Indicates whether there are unacknowledged changes from ongoing monitoring that require attention - `monitorStatus`: `string` Indicates if ongoing monitoring is enabled or disabled for this session, one of `enabled`, `disabled` - `searchTerm`: `object` Data used to perform the check - `name`: `string` Full name used during the check - `year`: `string` Birth year used during the check - `lists`: `array` List of watchlists against which the check was performed. Available only for [enhanced AML solution](/v1/docs/aml-screening-solution) - `countries`: `array` List of countries associated with the check, as ISO 3166-1 Alpha-2 country code. Available only for [enhanced AML solution](/v1/docs/aml-screening-solution) - `exactMatch`: `boolean` Indicates whether the name used in the check required an exact match. Available only for [enhanced AML solution](/v1/docs/aml-screening-solution) - `matchThreshold`: `integer` Configured matching percentage threshold. Available only for [enhanced AML solution](https://devdocs.veriff.com/docs/aml-screening-solution) - `excludeDeceased`: `boolean` Indicates whether deceased individuals were excluded from the check. Available only for [enhanced AML solution](/v1/docs/aml-screening-solution) - `totalHits`: `integer` Total number of hits returned from the check - `createdAt`: `string` Timestamp indicating when the check was performed - `hits`: `array` Check response hits array of matched records. Empty array if no hits were found - `id`: `string` Unique identifier of this hit. Use this ID when submitting review decisions via the PATCH endpoint - `matchStatus`: `string` Review decision for this specific hit, one of `false_positive`, `potential_match`, `true_match`, `inconclusive` - `riskLevel`: `string` Risk level for this hit, one of `low`, `high`. Only present when hit-level `matchStatus` is `true_match` - `matchedName`: `string` The name that was matched in this hit based on the search term - `countries`: `array` List of countries that sources listed in relation to this hit - `dateOfBirth`: `string` Birth date of the person in the matched listings - `dateOfDeath`: `string` Death date of the person in the matched listings - `matchTypes`: `array` Array that shows the match type in the listings. See [data provider's documentation](https://docs.complyadvantage.com/api-docs/?json#example-response-1)[↗] for possible values - `aka`: `array` Array of names that the matched person is also known as - `associates`: `array` Array of names that the matched person is associated with - `listingsRelatedToMatch`: `object` Matched listings. Optional, empty object if "PEP & Sanctions" add-on is not enabled - `warnings`: `array` Array of warning matches. Empty array if no warnings were found - `sourceName`: `string` Name of the listing - `sourceUrl`: `string` URL of the listing - `date`: `string | null` Date of the listing. `null` if listing does not have a date - `sanctions`: `array` Array of sanctions matches. Empty array if no sanctions were found - `sourceName`: `string` Name of the listing - `sourceUrl`: `string` URL of the listing - `date`: `string | null` Date of the listing. `null` if listing does not have a date - `fitnessProbity`: `array` Array of fitness probity matches. Empty array if no fitness probities were found - `sourceName`: `string` Name of the listing - `sourceUrl`: `string` URL of the listing - `date`: `string | null` Date of the listing. `null` if listing does not have a date - `pep`: `array` Array of PEP matches. Empty array if no PEP matches were found - `sourceName`: `string` Name of the listing - `sourceUrl`: `string` URL of the listing - `date`: `string | null` Date of the listing. `null` if listing does not have a date - `adverseMedia`: `array` Array of media matches. Empty array if no media were found - `sourceName`: `string` Name of the listing - `snippet`: `string` Text snippet of the related listing - `sourceUrl`: `string` URL of the listing - `date`: `string | null` Date of the listing. `null` if listing does not have a date --- ## Changelog | Date | Description | | --- | --- | | Jul 8, 2026 | - New fields added: `reviewStatus` (replaces deprecated `matchStatus` as the primary screening outcome indicator), `monitorStatus`, and `hasUnacknowledgedChanges`. - Each hit in the `hits` array now includes `id`, `matchStatus` (per-hit review decision), and `riskLevel`. - Added an "In a nutshell" orientation section linking to the AML Screening guides and API docs, a note on the `reviewStatus`-change webhook trigger, and a note that `reviewed` can revert to `potential_match`. | | Feb 10, 2026 | `searchTerm` object updated with `lists`, `countries`, `exactMatch`, `matchThreshold` and `excludeDeceased` keys | | Feb 2, 2026 | New string `snippet` added to `listingsRelatedToMatch.adverseMedia` object | | Jun 6, 2025 | Heading “Article versioning” changed to “Changelog” | | Apr 12, 2025 | Link added to `matchType` array, to provide access to array’s possible values | | Mar 12, 2025 | Documentation published | ## Related - [Webhooks Guide](/webhooks-guide.md) - [AML Screening (legacy)](/aml-screening.md)