Webhook - Application Status Change

Modulr sends this webhook to notify Partners of changes to a customer's application status as it progresses through the verification process.

You will receive this event multiple times across the lifecycle of an application. Your handler must be idempotent - the same event may be delivered more than once.

When it fires

When a customer starts entering data (transitions to IN_PROGRESS)
When automated CDD checks complete (transitions to APPROVED, PENDING_STEP_UP, or MANUAL_REVIEW)
When a manual review decision is made
When a step-up is requested post-submission

Payload

{
  "eventDateTime": "2026-04-27T13:19:34.457092669Z",
  "eventName": "APPLICATION_STATUS_CHANGE",
  "applicationId": "APP21000MG",
  "status": "IN_PROGRESS"
}

Fields

Field	Type	Description
`eventDateTime`	string (ISO 8601)	Timestamp of the status change.
`eventName`	string	Always `APPLICATION_STATUS_CHANGE`.
`applicationId`	string	The application ID associated with the event. Store this against your customer record.
`status`	string	The new application status. See Application Statuses for all possible values.

Status values

Status	What to do
`IN_PROGRESS`	No action. Store the status against your customer record.
`PENDING_STEP_UP`	Notify your customer that further information is required. Re-invoke the SDK with the same `applicationId`.
`MANUAL_REVIEW`	No action. Await the next status change.
`APPROVED`	Await the `CUSTOMER_CREATED` webhook to receive the `customerId`.
`DECLINED`	Notify the customer. They will not be onboarded.
`EXPIRED`	The customer must restart. Create a new application.

Handling PENDING_STEP_UP

When you receive a PENDING_STEP_UP status:

Notify your customer that further action is needed.
Request a fresh short-lived token (Step 5 of the integration guide).
Re-initialise the SDK with the same applicationId.
Open the SDK - it will automatically surface the step-up form for the outstanding requirements.

// 1. Get fresh token
// POST /onboarding-service/keys/onboarding/{applicationId}

// 2. Re-initialise SDK
const sdkInstance = await ModulrCustomerVerificationSdk.init({
  token,
  hmac,
  applicationId: 'APP21000MG',
  onInit: (result) => { /* ... */ },
  onError: (error) => { /* ... */ }
});

// 3. Open SDK
await sdkInstance.open({
  onResult: (data) => { /* ... */ },
  onError: (error) => { /* ... */ },
  onClose: () => { /* ... */ }
});

Implementation notes