Finished Step Webhook

The IDWise backend will send a JSON HTTP POST request to the webhook configured, with the following details:

{  
  "event": "Finished Step",  
  "body": {
    "eventId":"4****-****-****-*********7", 
    "journeyId": "6720***********22e",
    "referenceNo": "840...........23",  
    "stepId": 10,
    "stepType": "<STEP_TYPE>"
  }  
}

📘
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 step webhook this will always be Finished Step.

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.
stepId: The finished step's id.
stepType: The finished step's type. The expected value can be one of these:
- Selfie
- Document

AI integration prompt

Use this prompt with your AI coding assistant to generate a Finished Step Webhook handler for your backend stack. The generated handler should acknowledge IDWise quickly, then asynchronously run step-level processing for the completed document or selfie step.

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

View Integration Prompt

You are an expert backend engineer integrating the IDWise Finished Step 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 one journey step has finished, such as a Document step or Selfie step. Do not treat this webhook as proof that the full journey is complete. If all user-submitted steps must be complete, wait for the Finished User Steps webhook. If the final verification decision is required, wait for the Finished Journey webhook.

The webhook handler must:

1. Expose an HTTP POST endpoint that receives the IDWise Finished Step 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.stepId
   - body.stepType
4. Validate that the event value is Finished Step before processing the payload.
5. Validate that stepType is one of the expected values: Document or Selfie.
6. Log that the Finished Step webhook was triggered, including:
   - eventId
   - journeyId
   - referenceNo
   - stepId
   - stepType
7. Use eventId as an idempotency key so duplicate delivery attempts do not start the same step-level task 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 step images, run OCR, run face matching, or update the customer system before returning HTTP 200.
10. After returning HTTP 200, invoke an asynchronous method or background job named processFinishedStep or an equivalent name for the selected stack.
11. In the asynchronous method, use journeyId, referenceNo, stepId, and stepType to fetch any required journey or step details from IDWise, fetch the completed step images or documents if needed, and update the customer system with step-level progress.
12. Include examples for these Finished Step use cases where relevant:
   - Record that a document step or selfie step completed.
   - Start step-specific processing such as extracting document metadata, preparing a face comparison task, or updating an internal progress tracker.
   - Write an audit log for the completed step, including eventId, journeyId, referenceNo, stepId, and stepType.
13. Add error handling and logging inside the asynchronous method so processing failures are recorded without causing IDWise webhook delivery to time out.
14. 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 processFinishedStep method or background job code.
4. Required environment variables.
5. Example log output for a successful webhook trigger, including journeyId, referenceNo, stepId, and stepType.
6. Notes explaining why the handler returns HTTP 200 before fetching journey details, fetching images, or running downstream checks.
7. Notes explaining that Finished Step is a step-level event, not the final journey result.

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