---
title: "Watchlist-screening webhook"
slug: "wip-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 effectively."
updated: 2026-05-19T11:32:36Z
published: 2026-05-19T11:32:36Z
---

> ## 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.

The payload is sent to `Webhook watchlist screening URL`, which you need to set up the webhook in the Veriff Customer Portal.

> [!NOTE]
> **Same webhook** is used for both **legacy AML Sanctions** and [**enhanced AML Sanctions**](/v1/docs/aml-screening-solution) solutions’ sessions.
> 
> Main difference between the solution versions is that enhanced AML Sanctions offers more customization options regarding which lists to screen against, how strictly names are matched and how results are filtered.
> 
> Therefore, the enhanced AML Sanctions session’s webhook payload contains more parameters in the `searchTerm` object: `lists`, `countries`, `exactMatch`, `matchThreshold` and `excludeDeceased` keys.

→*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*

---

## 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**.

---

## 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)

5.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

### About `matchStatus` field

The `matchStatus` field is the primary outcome indicator of the AML/PEP screening itself. It directly answers the compliance question "Is this person flagged on any watchlist?"

The field has two possible values:

- `possible_match`: the person was found in one or more listings/databases. The `data.hits` array is populated with data about the person.
- `no_match`: the person was not found. The `data.hits` array is empty.

This is **independent from the session decision** (`approved`/`declined`), which is driven by IDV checks.

The confidence in the `matchStatus` is higher when combined with IDV, because the screening data was extracted from a verified document. In standalone mode, the accuracy of the screening depends on the quality of the data you input.

If you require more data, you can use the relevant `sessionId` and query the [GET sessions/{sessionId}/person](https://veriff-dev-documentation.document360.io/apidocs/v1sessionsidperson-1)[↗] endpoint to find more detailed info about the match. Look for data in the `person.pepSanctionMatches` array.

### Possible session outcomes

**Session**`approved`**+**`matchStatus`**:**`no_match`

This is the **ideal outcome**. The end-user’s identity was verified successfully and they were not found on any PEP/Sanctions/Adverse Media lists. You can proceed with onboarding, no further AML action needed.

**Session**`approved`**+**`matchStatus`**:**`possible_match`

The **end-user’s identity is verified** (the document and selfie are genuine), but they were **found on one or more watchlists**. Veriff only flags potential matches, you retain decisioning responsibility. Therefore, **you need to** **perform manual review**:

- Review the `hits` array to examine the matched listings (source names, URLs, match types, etc.).
- Determine whether the hit is a true match or a false positive (e.g., common name coincidence).
- Apply your own risk-based decision depending on your regulation and requirements (decline the end-user, apply enhanced due diligence, or escalate).

---

## Sample request

```json
{
   "id":"a3f8b2c1-1234-4abc-8def-0123456789ab",
   "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",
   "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":[
      {
         "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"
               }
            ]
         }
      }
   ]
}
```

## Request properties

*Required field

- `checkType`: `updated_result`* Indicates if the succession of the check, one of `intial_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`* Indicates the result of the search, one of `possible_match`, `no_match`
- `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 of string` List of watchlists against which the check was performed. Available only for [enhanced AML solution](/v1/docs/aml-screening-solution).
  - `countries`: `array of string` 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](/v1/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
  - `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 doesn't 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` Date of the listing. `Null` if listing doesn't 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 doesn't 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 doesn't 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 |
| --- | --- |
| May 19, 2026 | Distinction between [legacy AML](/v1/docs/aml-screening)and [enhanced AML](/v1/docs/aml-screening-solution) solutions added to article intro and to `lists`, `countries`, `exactMatch`, `matchThreshold` and `excludeDeceased` keys |
| 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 |