Finished Journey Webhook

The Finished Journey Webhook notifies your backend when a verification journey has completed processing and a final decision has been reached. Use this webhook to trigger downstream actions in your system — such as approving a user account, flagging an application for manual review, or blocking a rejected applicant.

When It Triggers

IDWise sends this webhook when:

A user completes all required steps in the journey and IDWise finishes processing the verification.
A journey is reprocessed after a KYC Renewal resubmission.
A manual review decision is made by a compliance reviewer.

The webhook fires once per event. If delivery fails, IDWise retries with the same eventId so you can deduplicate on your end.

Webhook Payload

IDWise sends an HTTP POST request to your configured webhook URL with the following JSON payload:

{  
  "event": "Finished Journey",  
  "body": {
    "eventId":"4****-****-****-*********7", 
    "journeyId": "6720***********22e",
    "referenceNo": "840...........23",  
    "systemDecision": "<SYSTEM_DECISION>"
  }  
}

📘
Note
Please note this object might be extended with extra elements. Ensure your code can accommodate any extra elements introduced to this payload object.

The JSON object provided contains information about certain events in the ID verification process. Here is the explanation of its elements:

event: Identifies the type of event that triggered this webhook. For finished journey webhook this will always be Finished Journey.

Inside the body element you find these elements:

eventId: A unique identifier to identify this event instance. Should the event be attempted again, the eventId will consistently remain unchanged throughout all retry attempts.
journeyId: A unique identifier for the journey, a specific instance of the verification process.
referenceNo: The reference number associated with the journey.
systemDecision: The automated decision by the IDWise system based on the inputs received.

AI integration prompt

Use this prompt with your AI coding assistant to generate a Finished Journey Webhook handler for your backend stack. The generated handler should acknowledge IDWise quickly, then process journey details asynchronously.

Copy this prompt into your AI coding assistant to generate a backend webhook handler for Finished Journey events.

View Integration Prompt

You are an expert backend engineer integrating the IDWise Finished Journey 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.

The webhook handler must:

1. Expose an HTTP POST endpoint that receives the IDWise Finished Journey 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
4. Validate that the event value is Finished Journey before processing the payload.
5. Log that the Finished Journey webhook was triggered, including:
   - eventId
   - journeyId
   - referenceNo
   - systemDecision as the verification status
6. Use eventId as an idempotency key so duplicate delivery attempts do not update the customer system more than once.
7. Return HTTP 200 to IDWise as soon as the payload is accepted and basic validation is complete.
8. Do not fetch journey details, fetch images, or update the customer system before returning HTTP 200.
9. After returning HTTP 200, invoke an asynchronous method or background job named processFinishedJourney or an equivalent name for the selected stack.
10. In the asynchronous method, fetch the journey details from IDWise using the journeyId, update the customer system using the journey details, and fetch any required images or documents for internal processing.
11. Add error handling and logging inside the asynchronous method so processing failures are recorded without causing IDWise webhook delivery to time out.
12. 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 processFinishedJourney method or background job code.
4. Required environment variables.
5. Example log output for a successful webhook trigger, including journeyId, referenceNo, and systemDecision.
6. Notes explaining why the handler returns HTTP 200 before fetching journey details or images.

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

Use Cases

Use Case	Description
User onboarding	Automatically activate a user account when `systemDecision` is `Complete`, or hold the account when the decision is `Refer` or `Rejected`.
Manual review queue	Route journeys with a `Refer` decision to your compliance team for manual review.
Rejection handling	Notify the user and block access when `systemDecision` is `Rejected`.
KYC renewal processing	After a user resubmits during KYC Renewal, use this webhook to update the user's verification status based on the new decision.
Audit logging	Record every finished journey event — including the `eventId`, `journeyId`, and decision — for compliance and audit trail purposes.