Journey Custom Steps API

Use custom-step APIs from your backend to submit additional verification data for an existing journey and finalize its outcome.

A custom step lets your backend provide data that the IDWise SDK does not capture. For example, you can retrieve a face image from a government database and submit it for comparison with the user's selfie or identity-document images.

⚠️
Backend use only
Call these APIs only from your backend. Do not use them in a client SDK integration.

Integration steps

Complete the user capture steps. The user completes the required ID and selfie capture steps in the SDK.
Subscribe to the Finished User Steps webhook. Configure your backend to receive the Finished User Steps webhook. It notifies your backend after the user submits all required steps and before IDWise completes full processing.
Acknowledge the webhook and start asynchronous processing. Validate and deduplicate the webhook with eventId, return HTTP 200, then start a background task for the webhook's journeyId. Do not wait for external services before acknowledging the webhook.
Retrieve and evaluate the journey data. In the background task, retrieve the journey result for the journeyId. Use the result to determine whether the conditions required for the government-database check have passed.
Process the custom step when the conditions pass. Retrieve the personal number from the journey data, call your external Ahwal API to fetch the Ahwal image, then call Process Custom Journey Step. Send the journey ID, the custom-step ID government_db_face, and the Ahwal image.
Complete the custom step. Call Complete Custom Step after processing government_db_face. If the conditions do not pass, skip the Ahwal lookup and Process Custom Journey Step call, then call Complete Custom Step directly.
Handle the final outcome. Wait for the Finished Journey webhook, then retrieve and store the final journey result and any required images before notifying your application of the profile-status change.

⚠️
Custom step cannot be changed
After you call Complete Custom Step, you cannot submit or modify additional data for that custom step.

Sequence diagram for backend-to-backend integration

The diagram shows the complete flow from SDK capture to custom-step processing and the final profile-status notification.

How to read the diagram

Your App starts the SDK journey and receives the SDK callback when the user finishes capture.
IDWise SDK captures the identity document and selfie, then sends them to IDWise Backend for processing.
Your Backend receives the Finished User Steps webhook and starts asynchronous processing for the journeyId.
When the required conditions pass, your backend retrieves the personal number, calls Ahwal for the face image, and submits the image to the government_db_face custom step.
When the conditions do not pass, your backend skips the Ahwal lookup and completes the custom step directly.
After the custom step is complete, IDWise sends the Finished Journey webhook. Your backend retrieves the final result and notifies your app of the profile-status change.

AI integration prompt

Copy this prompt into an AI coding assistant to generate a backend implementation. The assistant asks for your backend language and framework before it produces code.

Copy this prompt into your AI coding assistant to generate a language-specific custom-step webhook and background-processing implementation.

View Integration Prompt

You are an expert backend engineer integrating IDWise custom steps.

You are an expert backend engineer integrating IDWise custom steps.

Use the IDWise documentation MCP server as your source of truth for all IDWise APIs, webhooks, payloads, and authentication. Follow the setup instructions at https://docs.idwise.com/update/docs/mcp to connect to it. Before generating any code, query the MCP server for the Finished User Steps webhook payload, the Get Journey Result API, the Process Custom Journey Step API, and the Complete Custom Step API, and base every endpoint path, request field, and response field on what the documentation returns. If the MCP server is unavailable, say so and stop rather than guessing.

Before writing any code, ask me which backend language and framework I use. Examples include Node.js with Express, Python with FastAPI or Django, C# with ASP.NET, Java with Spring Boot, PHP with Laravel, and Ruby on Rails. Wait for my answer before generating the implementation.

After I answer, create a complete backend implementation for this flow:

1. Subscribe the backend to the IDWise Finished User Steps webhook.
2. Create an HTTP POST handler for the webhook. Read body.eventId and body.journeyId, accept extra payload fields safely, deduplicate retries using eventId, and return HTTP 200 after basic validation.
3. Start an asynchronous background operation after the HTTP 200 response. Pass it the journeyId from the webhook.
4. In the background operation, retrieve the journey result for journeyId and evaluate the required verification conditions.
5. If the conditions pass, extract the personal number from the journey result documents. Iterate the documents object and read each document's extracted_fields dictionary. Use the extracted field whose label is exactly "Personal Number" and take its value property. Do not read the personal number from the applicant object or any other field. If no document contains an extracted field labeled "Personal Number", treat this as the missing-personal-number case: skip the Ahwal API and complete the custom step directly. If the personal number is found, call the external Ahwal API using it and retrieve the Ahwal face image.
6. Submit the Ahwal image through Process Custom Journey Step. Use the journey ID and set the custom-step ID exactly to government_db_face.
7. Call Complete Custom Step after submitting the Ahwal image.
8. If the conditions do not pass, do not call the Ahwal API and do not process government_db_face. Call Complete Custom Step directly to complete the journey.
9. Handle the Finished Journey webhook separately for the final journey outcome. Do not treat the Finished User Steps webhook as the final verification decision.

The implementation must include:

- A webhook subscription and handler setup for the selected stack.
- Complete runnable code with imports, initialization, validation, error handling, logging, and response handling.
- An asynchronous background job or method for the custom-step flow.
- Idempotency for duplicate Finished User Steps webhook deliveries using eventId.
- A clear condition branch for pass and fail paths.
- A personal-number extraction function that searches documents.*.extracted_fields for the key labeled exactly "Personal Number" and returns its value, with a defined fallback behavior when it is absent (skip Ahwal, complete the custom step, and log the reason).
- Placeholders for the IDWise API credentials, Ahwal API credentials, webhook URL, and any URLs not supplied here. Store all credentials in environment variables or the stack's secret-management system.
- Example log output for successful processing, skipped Ahwal processing, and failures.
- A short test checklist for the webhook handler, pass path, fail path, duplicate webhook delivery, missing Personal Number field, and external Ahwal API failure.

Do not expose secrets in source code. Do not invent IDWise SDK methods, API paths, request fields, response fields, or authentication details. Every IDWise-specific detail must come from the IDWise documentation MCP server.

Journey custom step APIs

API	Use it to
Process Custom Journey Step	Submit additional verification data for an existing journey, such as an Ahwal face image for comparison with an existing selfie or document. Use `government_db_face` as the custom-step ID for this flow.
Complete Custom Step	Close the custom step and request the system decision using the data submitted so far. You cannot submit or change more custom-step data afterward.