IDWise Webhooks
Table of contents
It is essential that you use IDWise webhooks for your backend-to-backend integration. Webhooks are used to send notifications from the IDWise backend to your server via simple secure HTTPS calls.
Not Already a Customer?
Types of webhooks:
There are two types of webhooks supported by IDWise:
Journey Completed Webhook:
This webhook is triggered when the journey has been completed and processing is finalised on the IDWise backend.
Manual Review Webhook:
This webhook is triggered once a manual review has been completed on the IDWise dashboard (where the system decision was either confirmed or overridden by a dashboard user).
AML Monitor Update Webhook:
The webhook is triggered whenever there is an update to a monitored AML record. For instance, if a person has been added to a sanctions list or is no longer considered politically exposed, the webhook will be activated.
Finished User Steps Webhook:
This webhook is triggered when a user completes all the required steps and submits them to IDWise backend. this webhook notifies the customer backend that the user steps have been completed, If any custom steps are necessary, the customer backend can initiate them at this point, such as submitting the face from the government database to compare it with the user’s selfie face.
Configuring webhooks:
If interested, please send the webhook URL(s) you want to use to support@idwise.com to allow the team to add it to your configuration.
Experimental webhook (for testing):
You can also use a website called https://webhook.site/ to get a webhook that you can use during the development and testing phase (on top of your app webhook); IDWise supports adding multiple URLs as webhooks.
Implementing Webhook Handler:
You need to create a publicly accessible webhook endpoint for IDWise to send notifications to. This webhook endpoint will receive a JSON payload every time a new notification is triggered. The JSON payload will contain the details of the notification.
The webhook endpoint created for IDWise might be triggered multiple times for the same journey. It is essential to ensure that the handler is designed to handle such scenarios. Your handler code needs to be idempotent (where multiple identical requests have the same effect as a single request, meaning that the API has the same result whether it is called once or multiple times.)
How does it work?
The webhook mechanism is essentially a way for IDWise to inform your backend of updates on a particular journey, for example, when the journey is complete.
The IDWise server will send a JSON HTTP POST request to the URL configured, with the following details:
{
"event": "**EVENT_NAME**",
"body": {
"journeyId": "62e6...........5d0c",
"referenceNo": "840...........23",
"systemDecision": "**SYSTEM_DECISION**",
"manualDecision": "**MANUAL_DECISION**",
"finalDecision": "**FINAL_DECISION**"
}
}
Here are the possible values:
EVENT_NAME
It represents the event concerned, as mentioned above, we support:
- Finished Journey
- Manually Reviewed
- AML Monitor Update
- Finished User Steps
SYSTEM_DECISION
It can be one of the following:
- Complete: The journey has been successfully completed (it shows on the UI as passed).
- Incomplete: The journey has not been completed yet (the user didn’t finish all steps).
- Refer: At least one of the steps has failed, and the journey needs to be referred for a manual review.
MANUAL_DECISION:
It can be one of the following:
- null: The journey has not been reviewed yet by a manual reviewer.
- Approved: The journey has been approved by a manual reviewer.
- Rejected: The journey has been rejected by a manual reviewer.
FINAL_DECISION:
It can be one of the following:
- Approved: The journey has been approved by a manual reviewer.
- Rejected: The journey has been rejected by a manual reviewer.
- Complete: The journey has been successfully completed (it shows on the UI as passed).
- Incomplete: The journey has not been completed yet (the user didn’t finish all steps).
- Refer: At least one of the steps has failed, and the journey needs to be referred for a manual review.
Webhooks Sequence Diagram:
