Create a webhook configuration

post

https://api.mesh.complyadvantage.com/v2/notifications/configurations/webhook

Creates a webhook configuration that monitors an event type and sends updates to the URL you specify.

There are several event types you can listen to:

CASE_CREATED

Receive an update whenever a new case is created.

Note:

case_state is deprecated. Please use case_stage instead.
This webhook produces two responses v1 and v2 - please use v2 as it contains case_stage and also the customer external_identifier

Example:

{
 "api_version": "v2",
 "webhook_type": "CASE_CREATED",
 "case_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "case_state": "ONBOARDING_NOT_STARTED",
 "case_type": "CUSTOMER_ONBOARDING",
 "customer": {
  "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "external_identifier": "your unique customer identifier",
  "version": 1
 },
 "case_stage": {
   "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "display_name": "Not Started",
   "display_order": 1,
   "stage_type": "INITIAL",
   "decision_type": null
 },
 "subjects": [
   {
     "type": "CUSTOMER",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique customer identifier",
     "version": "1"
   },
   {
     "type": "TRANSACTION",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique transaction identifier"
   },
   {
     "type": "COUNTERPARTY",
     "external_identifier": "your unique counterparty identifier"
   }
 ]
}

CASE_TRANSITIONED

Receive an update whenever a case changes its stage, e.g. from "Not Started" to "In Progress".

Note:

case_state is deprecated. Please use case_stage instead.
This webhook produces two responses v1 and v2 - please use v2 as it contains case_stage and also the customer external_identifier
Replaces webhook type CASE_STATE_UPDATED (deprecated) — existing deprecated subscriptions continue to be functional.

Example:

{
 "api_version": "v2",
 "webhook_type": "CASE_TRANSITIONED",
 "case_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "case_state": "CASE_STATE_POSITIVE_END_STATE",
 "case_type": "CUSTOMER_ONBOARDING",
 "customer": {
  "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "external_identifier": "your unique customer identifier",
  "version": 1
 },
 "note": {
  "contents": "note left at the time the case state was updated"
 },
 "case_stage": {
   "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "display_name": "False Positive",
   "display_order": 4,
   "stage_type": "DECISION",
   "decision_type": "POSITIVE"
 },
 "subjects": [
   {
     "type": "CUSTOMER",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique customer identifier",
     "version": "1"
   },
   {
     "type": "TRANSACTION",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique transaction identifier"
   },
   {
     "type": "COUNTERPARTY",
     "external_identifier": "your unique counterparty identifier"
   }
 ]
}

CASE_ALERT_LIST_UPDATED

Receive an update whenever the alert list associated with a case is updated, such as when new alerts are added to the case.

Example:

{
 "api_version": "v2",
 "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 "webhook_type": "CASE_ALERT_LIST_UPDATED",
 "case_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "customer": {
  "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "external_identifier": "your unique customer identifier",
  "version": 1
 },
 "alert_identifiers": [
   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
   "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
 ],
 "subjects": [
   {
     "type": "CUSTOMER",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique customer identifier",
     "version": "1"
   },
   {
     "type": "TRANSACTION",
     "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
     "external_identifier": "your unique transaction identifier"
   },
   {
     "type": "COUNTERPARTY",
     "external_identifier": "your unique counterparty identifier"
   }
 ]
}

WORKFLOW_COMPLETED

Receive an update when an onboarding workflow completes.

Example:

{
  "api_version": "v2",
  "webhook_type": "WORKFLOW_COMPLETED",
  "workflow_instance_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "step_details": {
    "alerting": {
      "identifier": null,
      "status": "COMPLETED",
      "step_output": {
      "alerts": [
          {
            "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }
        ]
      }
    },
    "customer-creation": {
        "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "COMPLETED",
        "step_output": {
        "customer_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    },
    "customer-screening": {
      "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "COMPLETED",
      "step_output": {
        "screening_result": "HAS_PROFILES",
        "aml_types": [
          "SANCTION",
          "ADVERSE_MEDIA",
          "ADVERSE_MEDIA_V2_CYBERCRIME",
          "PEP_CLASS_1",
          "PEP_CLASS_2",
          "WARNING"
        ]
      }
    },
    "initial-risk-scoring": {
        "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "COMPLETED",
        "step_output": {
        "overall_level": "LOW-RISK",
        "overall_value": 0
      }
    }
  },
  "steps": [
    "customer-creation",
    "initial-risk-scoring",
    "customer-screening",
    "alerting"
  ],
  "workflow_type": "create-and-screen"
}

TRANSACTION_REVIEWED

Receive an update when a transaction has been reviewed and either released or rejected.

Example:

{
  "api_version": "v3",
  "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "webhook_type": "TRANSACTION_REVIEWED",
  "transaction_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "transaction_external_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "evaluation_outcome": "HOLD",
  "review_decision": "RELEASE"
}

CUSTOMER_RISK_SCORE_CHANGED

Receive an update whenever a customer's risk score value changes.

Example:

{
  "api_version": "v3",
  "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "webhook_type": "CUSTOMER_RISK_SCORE_CHANGED",
  "customer_external_identifier": "your unique customer identifier",
  "risk_score": {
    "score": 75.0,
    "level": "HIGH",
    "manual_override": false,
    "categories_scores": [
      {
        "category_type": "AML",
        "score": 85.0,
        "weight": 0.5,
        "level": "HIGH",
        "risk_attributes": []
      }
    ]
  },
  "previous_risk_score": {
    "score": 50.0,
    "level": "MEDIUM",
    "manual_override": false,
    "categories_scores": []
  }
}

CUSTOMER_RISK_LEVEL_INCREASED

Receive an update whenever a customer's risk level increases (e.g., from MEDIUM to HIGH).

Example:

{
  "api_version": "v3",
  "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "webhook_type": "CUSTOMER_RISK_LEVEL_INCREASED",
  "customer_external_identifier": "your unique customer identifier",
  "risk_score": {
    "score": 85.0,
    "level": "HIGH",
    "manual_override": false,
    "categories_scores": []
  },
  "previous_risk_score": {
    "score": 50.0,
    "level": "MEDIUM",
    "manual_override": false,
    "categories_scores": []
  }
}

CUSTOMER_RISK_LEVEL_DECREASED

Receive an update whenever a customer's risk level decreases (e.g., from HIGH to MEDIUM).

Example:

{
  "api_version": "v3",
  "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "webhook_type": "CUSTOMER_RISK_LEVEL_DECREASED",
  "customer_external_identifier": "your unique customer identifier",
  "risk_score": {
    "score": 45.0,
    "level": "MEDIUM",
    "manual_override": false,
    "categories_scores": []
  },
  "previous_risk_score": {
    "score": 80.0,
    "level": "HIGH",
    "manual_override": false,
    "categories_scores": []
  }
}

CUSTOMER_LABELS_CHANGED

Sent whenever labels are added to or removed from a customer.

Each event states what changed - the labels added and the labels removed - and includes the complete
set of labels on the customer after the change. The label arrays are always present, and empty where
nothing was added or removed.

Example:

{
  "webhook_type": "CUSTOMER_LABELS_CHANGED",
  "api_version": "v3",
  "account_identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "customer": {
    "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "external_identifier": "your unique customer identifier",
    "version": 3
  },
  "added_labels": [
    { "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "PEP high" }
  ],
  "removed_labels": [
    { "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "PEP low" }
  ],
  "labels": [
    { "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "PEP high" },
    { "identifier": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "ADM low" }
  ],
  "updated_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "updated_at": "2026-08-11T14:22:31Z"
}

TRANSACTION_MONITORING_ASYNC_COMPLETED

Receive an update when an asynchronous transaction monitoring evaluation has completed.

Example:

{
  "api_version": "v2",
  "webhook_type": "TRANSACTION_MONITORING_ASYNC_COMPLETED",
  "webhook_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "transaction_external_id": "your unique transaction identifier",
  "transaction_version": 1,
  "monitoring_outcome": "HOLD",
  "scenario_evaluations": [
    {
      "scenario_configuration_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "evaluation_results": [
        {
          "scenario_identifier": {
            "scenario_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "version": 0
          },
          "scenario_name": "Over 1000 USD",
          "priority": 1,
          "scenario_outcome": "HOLD"
        }
      ]
    }
  ]
}

URL checks

This endpoint checks the URL in the order below. If a check fails, you get a 400, the remaining checks do not run, and the configuration is not created.

The scheme must be http or https. Otherwise, the error key is error.validation.WebhookUrlScheme. Scheme names are not case-sensitive.
The URL must be valid. Otherwise, the error key is error.validation.ValidWebhookUrl.
An http URL requires allow_insecure_http set to true. Otherwise, the error key is error.validation.WebhookUrlScheme.
This endpoint sends one HEAD request to your URL:
- If the host resolves only to IANA special-purpose IPv4 addresses, no request is sent and the error key is error.validation.ValidWebhookUrl.
- If the server presents a TLS certificate that is expired, untrusted, or does not match the host name, the error key is error.validation.WebhookCertificate.
- If the request gets no HTTP response, the error key is error.validation.WebhookUrlUnreachable. This covers a host name that does not resolve, a refused or timed-out connection, and a TLS handshake that fails for a reason other than the certificate (for example, a server that only supports TLS versions below 1.2).
- Any HTTP status code passes, because the server responded.

http and https

We recommend an https URL. Webhooks to an https URL use TLS 1.2 or higher.

To use an http URL, set allow_insecure_http to true. The traffic is unencrypted.

Permissions

You need the "Create and update webhooks" permission to use this endpoint.

Body Params

allow_insecure_http

boolean | null

Defaults to false

Set to true to use an http URL. null means false. Ignored for an https URL.

is_active

boolean

required

Defaults to true

This flag sets whether the webhook is in use or not. If 'true' Mesh sends updates when the monitored events take place. If 'false', Mesh will not send any updates. If unset default value will always be true.

name

string

required

The name of the webhook configuration.

type

string | null

enum

required

The type of webhook notification configuration being created.

CASE_STATE_UPDATED is deprecated (replaced by CASE_TRANSITIONED)

url

uri

required

The client side URL that webhooks are sent to. We strongly recommend https. To use http, set allow_insecure_http to true. The scheme must be http or https, and the host must not resolve only to IANA special-purpose IPv4 addresses. For an https URL, the TLS certificate must match the host name, be trusted, and not be expired. See "URL checks" in the endpoint description.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Callbacks

201Webhook configuration created successfully

400Bad request. Request cannot be processed due to input webhook configuration payload error.