MBTRUST_FAILURE Event

This webhook event is sent when an MBTrust account provisioning operation fails. This includes failed onboarding operations, document sync failures, and merchant update errors.

When This Event Is Sent

The endpoint mbtrust.execute is used, and the execution falis.
A user performs an MBTrust execution from the Underwriters Dashboard, and the execution fails.

Decrypted Data Parameters

This event includes all default parameter for version 1.0 in the decrypted data parameter, plus the following parameters:

Parameter	Type	Required	Description
provisioning_data	object	Yes	Complete MBTrust provisioning entity data including error details. See MBTrust Parameters below.

MBTrust Parameters

The provisioning_data object contains the complete MBTrust provisioning entity state, identical to the response from mbtrust.get.

For detailed documentation of all fields in the provisioning_data object, refer to the mbtrust.get endpoint documentation.

Check the errors array within execution_results for specific failure details.

Example Payload

Note: This example shows the decrypted payload. When you receive this webhook, the data field will be encrypted. See the encryption reminder for details.

{
  "id": "wh_4Y0zmCf23xYl73HGHuDVrL",
  "event_type": "MBTRUST_FAILURE",
  "timestamp": "2026-03-17T21:57:46Z",
  "account_id": "account_id",
  "schema_version": "2025-11-21",
  "key_id": "whk_20260317_01",
  "data": {
    "version": "1.0",
    "subject_record_id": "sr_3qdwxc1uypBuVtU7t06ePH",
    "workflow_id": "w_VQXsx0t2ullUWEW917UxE",
    "workflow_type": "ACCOUNT_PROVISIONING",
    "user_context": {
      "user_id": "SYSTEM",
      "user_type": "SYSTEM"
    },
    "provisioning_data": {
      "provisioning_type": "MBTRUST",
      "provisioning_sponsor": "MERRICK",
      "status": "FAILED",
      "created_at": "2026-03-17T21:51:32.657Z",
      "updated_at": "2026-03-17T21:51:32.660Z",
      "mbtrust_id": "ape_6NlMsHSyHB2G8KNWD0Xreu",
      "execution_results": [
        {
          "status": "FAILED",
          "started_at": "2026-03-09T17:12:40.566Z",
          "operation_id": "apo_ZlJAl6KE8eCX4WrmPM8IZ",
          "operation_type": "document_sync",
          "errors": [
            {
              "code": "ENTITY_NOT_FOUND",
              "message": "The given entity(s) does not exist.",
              "details": [
                {
                  "document_id": "d_6yvQZTsG0090jq4Vd3ucbf"
                }
              ]
            }
          ],
          "provider_response": {}
        }
      ]
    }
  }
}

Error Handling

When you receive an MBTRUST_FAILURE event:

Check the status field in provisioning_data (will be FAILED)
Examine the execution_results array for operation-specific errors
Review the errors array within each execution result for detailed error information
Use error codes to determine the appropriate remediation action
Consider calling mbtrust.get to retrieve the latest entity state if needed