Verification Update Required Webhook

You are an expert backend engineer integrating the IDWise Verification Update Required Webhook.

Before writing any code, ask me which backend stack, language, and framework I am using. Examples: Node.js with Express, Python with FastAPI, Python with Django, C# with ASP.NET, Java with Spring Boot, PHP with Laravel, Ruby on Rails, or another stack.

After I answer, generate a complete webhook handler for that stack.

This webhook means a verification journey requires the user to complete or resubmit one or more steps. The update can be triggered by a Manual Review Resubmission or by KYC Renewal.

The webhook handler must:

1. Expose an HTTP POST endpoint that receives the IDWise Verification Update Required webhook payload.
2. Parse the JSON payload without failing if IDWise adds extra fields in the future.
3. Read these fields from the payload:
   - event
   - body.eventId
   - body.journeyId
   - body.referenceNo
   - body.systemDecision
   - body.manualDecision
   - body.finalDecision
   - body.trigger
   - body.requiredSteps
4. Validate that the event value is Verification Update Required before processing the payload.
5. Validate that requiredSteps exists and is an array.
6. Log that the Verification Update Required webhook was triggered, including:
   - eventId
   - journeyId
   - referenceNo
   - systemDecision
   - manualDecision
   - finalDecision
   - trigger
   - requiredSteps count
7. Use eventId as an idempotency key so duplicate delivery attempts do not update the customer system or notify the user more than once.
8. Return HTTP 200 to IDWise as soon as the payload is accepted and basic validation is complete.
9. Do not fetch journey details, fetch images, update the customer system, send notifications, or run renewal workflows before returning HTTP 200.
10. After returning HTTP 200, invoke an asynchronous method or background job named processVerificationUpdateRequired or an equivalent name for the selected stack.
11. In the asynchronous method, route each supported trigger to a separate sub-handler. Do not implement all trigger handling in one large function.

Create separate sub-handlers for these triggers:

- handleManualReviewResubmission
- handleKYCRenewal
- handleUnknownVerificationUpdateTrigger

Each sub-handler must receive a normalized event object that includes eventId, journeyId, referenceNo, systemDecision, manualDecision, finalDecision, trigger, and requiredSteps.

Trigger-specific behavior:

1. Manual Review Resubmission:
   - Treat this as a reviewer-requested update where the user must resubmit one or more steps.
   - Fetch journey details from IDWise using journeyId if the customer system needs step names, document type, applicant contact details, or other metadata.
   - Call a dedicated method named handleRequiredStepResubmission or an equivalent name for the selected stack.
   - Update the customer system so the journey or application is marked as awaiting user resubmission.
   - Notify the end user with clear step-level instructions.
   - Record an audit log.

2. KYC Renewal:
   - Treat this as a renewal request based on the configured KYC renewal policy.
   - Fetch journey details from IDWise using journeyId if needed.
   - Update the customer system so the user or case is marked as requiring KYC renewal.
   - Notify the end user that identity verification must be renewed.
   - Include requiredSteps in the notification when available.
   - Record an audit log.

Required step resubmission behavior:

Implement handleRequiredStepResubmission as a separate method.

This method must:

1. Confirm that requiredSteps exists and is an array.
2. Iterate through each item in requiredSteps.
3. For each required step, read:
   - stepId
   - reasonCode
   - any available step metadata from fetched journey details, if needed
4. Generate a user-facing message for each required step based on reasonCode.
5. Treat reasonCode values as platform-level configurable codes, not hard-coded universal IDWise values. Examples may include document_expired, document_quality_bad, face_not_clear, missing_information, document_not_supported, or information_mismatch.
6. Implement a configurable reason-code-to-message mapping with safe fallback text for unknown reason codes.
7. Example messages:
   - document_expired: Your document appears to be expired. Please upload a valid, unexpired document.
   - document_quality_bad: We could not clearly read your document. Please retake the photo in good lighting and make sure all edges are visible.
   - face_not_clear: Your selfie was not clear enough. Please retake the selfie with your face fully visible.
   - missing_information: Some required information was missing. Please review the requested step and submit it again.
   - document_not_supported: The document you submitted is not supported for this verification. Please submit one of the accepted document types.
   - information_mismatch: Some information did not match the submitted verification details. Please review and resubmit the requested step.
   - unknown fallback: We need you to resubmit this verification step. Please review the instructions and try again.
8. Combine the step-level messages into a resubmission notification payload for the end user.
9. Determine which notification method the customer backend should use based on the customer's existing system configuration. Support at least:
   - Email notification
   - Push notification
   - Both email and push notification
   - No direct notification, only update internal state
10. Implement a notification dispatch method named notifyUserAboutVerificationUpdate or an equivalent name for the selected stack.
11. The notification dispatch method must not assume a specific vendor. Use adapter interfaces or placeholder methods for the customer's email provider and push notification provider.
12. Record an audit log containing eventId, journeyId, referenceNo, trigger, required step IDs, reason codes, and notification method used.

Asynchronous processing requirements:

1. processVerificationUpdateRequired must fetch journey details from IDWise using journeyId when a sub-handler needs current journey state, applicant contact details, step metadata, documents, images, or renewal context.
2. Any journey-detail, image, document, or applicant-metadata fetching must happen asynchronously after HTTP 200 is returned to IDWise.
3. Add error handling and logging inside processVerificationUpdateRequired and inside each trigger sub-handler so failures are recorded without causing IDWise webhook delivery to time out.
4. Keep IDWise API credentials out of source code by using environment variables or the stack's secret-management approach.

Return:

1. A short implementation checklist.
2. Complete runnable webhook handler code for the selected stack.
3. The asynchronous processVerificationUpdateRequired method or background job code.
4. Separate sub-handler methods for each trigger.
5. A dedicated handleRequiredStepResubmission method.
6. A configurable reason-code-to-message mapping with fallback handling.
7. A notification dispatch abstraction that can support email, push notification, both, or internal-state-only handling.
8. Required environment variables.
9. Example log output for a successful Verification Update Required webhook trigger.
10. Example log output for a Manual Review Resubmission event with requiredSteps.
11. Example log output for a KYC Renewal event.
12. Notes explaining why the handler returns HTTP 200 before fetching journey details, updating the customer system, or notifying the end user.

Do not build this as a frontend handler. The webhook endpoint must run on a trusted backend.