Finished User Steps Webhook

Handle Finished User Steps webhook events from IDWise, log submitted journey details, and process submission-complete tasks asynchronously before the final verification decision.

The Finished User Steps Webhook notifies your backend as soon as a user finishes submitting all required steps in the journey (e.g., ID document and selfie) โ€” before IDWise completes its full processing. Use this webhook to trigger backend tasks that depend on user submissions being complete but do not need to wait for the final verification decision.


When It Triggers

IDWise sends this webhook when:

  • The user has submitted all required steps in the journey (e.g., document capture, selfie capture).
  • IDWise may still be processing the submissions at this point โ€” the systemDecision reflects the decision at the time of the webhook, not necessarily the final outcome.

This webhook fires before the Finished Journey Webhook. If you need the final verification decision, wait for the Finished Journey Webhook instead.

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 User Steps",  
  "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 user steps webhook this will always be Finished User Steps.

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 User Steps Webhook handler for your backend stack. The generated handler should acknowledge IDWise quickly, then asynchronously run tasks that can start once the user has submitted all required steps.

Finished User Steps Webhook Handler Prompt

AI PromptWebhook handler

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

View Integration Prompt
You are an expert backend engineer integrating the IDWise Finished User Steps 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 the user has submitted all required journey steps, such as document capture and selfie capture, but IDWise may still be processing the submissions. Do not treat systemDecision in this webhook as the final verification decision. If final approval, rejection, or referral handling is required, wait for the Finished Journey webhook instead.

The webhook handler must:

1. Expose an HTTP POST endpoint that receives the IDWise Finished User Steps 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 User Steps before processing the payload.
5. Log that the Finished User Steps webhook was triggered, including:
   - eventId
   - journeyId
   - referenceNo
   - systemDecision as the current non-final status
6. Use eventId as an idempotency key so duplicate delivery attempts do not start the same downstream task 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, run face matching, run external checks, or update the customer system before returning HTTP 200.
9. After returning HTTP 200, invoke an asynchronous method or background job named processFinishedUserSteps or an equivalent name for the selected stack.
10. In the asynchronous method, fetch the journey details from IDWise using the journeyId, fetch any required submitted images or documents, and then run submission-complete tasks that do not require the final IDWise verification decision.
11. Include examples for these Finished User Steps use cases where relevant:
   - Trigger a face comparison between the submitted selfie and an image from the customer database or a third-party source.
   - Start backend verification tasks such as address verification or credit checks in parallel with IDWise processing.
   - Update the user experience by marking the submission as received and processing in the customer system.
   - Write an audit log recording when the user completed all required steps, including eventId, journeyId, and referenceNo.
12. Add error handling and logging inside the asynchronous method so processing failures are recorded without causing IDWise webhook delivery to time out.
13. 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 processFinishedUserSteps method or background job code.
4. Required environment variables.
5. Example log output for a successful webhook trigger, including journeyId, referenceNo, and the current systemDecision.
6. Notes explaining why the handler returns HTTP 200 before fetching journey details, fetching images, or running downstream checks.
7. Notes explaining that the Finished User Steps webhook is not the final verification result and that final decision handling belongs in the Finished Journey webhook.

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

Use Cases

Use CaseDescription
Face match with external sourceTrigger a face comparison between the submitted selfie and an image from your own database or a third-party source as soon as the user finishes submitting.
Backend verification tasksKick off additional backend checks (e.g., address verification, credit checks) that can run in parallel with IDWise processing.
User experience updatesNotify the user that their submissions were received and that processing is underway, improving the perceived responsiveness of your onboarding flow.
Audit loggingRecord the exact moment the user completed all steps โ€” including the eventId, journeyId, and reference number โ€” for compliance and audit trail purposes.

Did this page help you?