Upon the creation of a new request, the system sends a webhook containing the following information:
{
"id": "6ab40b53-9211-4a30-8921-a7679d392ff2",
"type": "STATUS_UPDATE",
"createdAt": "2025-05-26T15:50:11.924991541Z",
"request": {
"requestId": "947ef148-f6c6-40d8-98aa-2336be863fcc",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "CREATED"
}
}Webhook content upon voucher creation
The webhook sent upon voucher creation contains the following fields:
- id: unique identifier of the notification sent via webhook.
- type: type of event generated (e.g., request_created).
- createdAt: date and time of notification sending (ISO 8601 format).
- requestId: unique identifier of the request generated upon voucher creation.
- requestTypeId: identifier of the type of onboarding flow used (e.g., identification & signature, SPID, etc.), specific to the customer's environment.
- status: status associated with the notified event.
{
"id": "a3bf4717-5333-4a28-a34f-ef9dfcafa190",
"type": "STATUS_UPDATE",
"createdAt": "2025-05-26T15:50:12.055348856Z",
"request": {
"requestId": "947ef148-f6c6-40d8-98aa-2336be863fcc",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING"
}
}Once the request is created, the onboarding status immediately transitions from Created to Running, indicating the actual start of the process by the end user.
{
"id": "585c3069-06fc-498b-8ff4-60441a92c98b",
"type": "STATUS_UPDATE_ACTOR",
"createdAt": "2025-05-26T15:56:08.75025711Z",
"request": {
"requestId": "5b39ab29-d8d9-46b2-92e7-58d313f8d386",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "ACTIVE"
}
}Monitoring the status and steps of the flow
Following the initiation of the request, the system provides an indication of the current step the end user has reached within the onboarding flow.
The overall status remains set to Running for the entire duration of the process. At the same time, the stepName field varies dynamically based on the specific phase in which the user is located.
For example, in the case of the standard flow, the first step is represented by the reading and acceptance of the Terms and Conditions (T&C) of the Namirial Onboarding (NOB) product, which is notified through the corresponding value in the stepName field.
{
"id": "1cf084e0-1a8f-47dc-94bb-f647fed2f9cd",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-26T15:56:08.75220309Z",
"request": {
"requestId": "5b39ab29-d8d9-46b2-92e7-58d313f8d386",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "ACTIVE",
"stepName": "termsAndConditions",
"stepId": "termsAndConditions",
"stepStatus": "ACTIVE"
}
}Start of the identification process
Once the user has accepted the Terms and Conditions, the flow continues with the initiation of the recognition process, for example, through the ID Self form. At this stage, a new webhook notification is sent containing:
- stepName: set to Identification, indicating that the user has reached the identification phase.
- stepStatus: suggests that the identification process has been started, but not yet completed.
This information enables the client to track the user's progress through the recognition phase, clearly distinguishing it from its completion.
{
"id": "171e86c5-0f91-48aa-a7ab-27b6207d13a4",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-26T15:58:36.625346924Z",
"request": {
"requestId": "5b39ab29-d8d9-46b2-92e7-58d313f8d386",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "ACTIVE",
"stepName": "identification",
"stepId": "identification",
"stepStatus": "ACTIVE"
}
}Completion of the identification process
At the end of the identification procedure, the system sends an additional notification via webhook.
In this case:
- stepName remains set as Identification,
- While stepStatus takes the value 'Done', indicating that the identification process has been completed.
This information allows the client to detect the user's transition beyond the identification phase and to proceed with the subsequent steps outlined in the flow.
{
"id": "649717fa-6ee8-4eb2-bc0d-f5115220a9ca",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-27T07:32:34.839951445Z",
"request": {
"requestId": "13f577fd-6faf-4be4-b106-aa4799ad84f5",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "ACTIVE",
"stepName": "identification",
"stepId": "identification",
"stepStatus": "DONE"
}
}Start of the signing process
Following the completion of the identification process, if it is expected and no blocking errors occur in recognizing the type of identity document, the signing process of the document configured during the request creation phase is automatically initiated.
The system then sends a new webhook with the following information:
- status: remains set to Running, indicating that the flow is still ongoing;
- stepName: populated with Signature, indicating the start of the signing phase;
- stepStatus: takes the value Active, which signals the activation of the signing process by the user.
This notification enables the client to detect when the user enters the document signing phase.
{
"id": "69401f7c-bd8f-4d41-a87a-afbae99630e2",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-27T07:32:35.696625426Z",
"request": {
"requestId": "13f577fd-6faf-4be4-b106-aa4799ad84f5",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "ACTIVE",
"stepName": "signature",
"stepId": "signature",
"stepStatus": "ACTIVE"
}
}Completion of the signature process
At the end of the signing phase, the system sends a new webhook notification confirming the completion of the Signature step.
In particular, the message will contain:
- stepName: Signature
- stepStatus: Done, indicating that the signing process has been successfully completed by the user.
This notification enables the client to recognize the completion of the subscription phase and proceed with any subsequent activities.
{
"id": "05e507fd-7439-45a5-a482-1b372d97ae58",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-27T07:36:42.236611961Z",
"request": {
"requestId": "13f577fd-6faf-4be4-b106-aa4799ad84f5",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "DONE",
"stepName": "signature",
"stepId": "signature",
"stepStatus": "DONE"
}
}Completion Event and Access to the Thank You Page
The user's arrival at the Thank You Page generates the sending of a dedicated event via webhook, signaling the visible completition of the onboarding flow.
This event allows the client to track the completion of the process and to trigger any post-processing actions or confirmation communications.
{
"id": "5c32b9aa-2ee8-4cf1-ba9d-c41e98dc8c9d",
"type": "STATUS_UPDATE_STEP",
"createdAt": "2025-05-27T07:36:42.238092702Z",
"request": {
"requestId": "13f577fd-6faf-4be4-b106-aa4799ad84f5",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "RUNNING",
"actor": "userToIdentify",
"actorStatus": "DONE",
"stepName": "thankYou",
"stepId": "thankYou",
"stepStatus": "DONE"
}
}Process Completion Status
At the successful completion of the entire onboarding process, the webhook will send an event with the status set to Completed, indicating that the procedure has concluded successfully.
This notification allows the client to confirm the definitive conclusion of the flow and to proceed with the subsequent planned activities.
{
"id": "0554739c-a361-4203-8bb7-6df1b959ef5c",
"type": "STATUS_UPDATE",
"createdAt": "2025-05-27T07:36:42.324640453Z",
"request": {
"requestId": "13f577fd-6faf-4be4-b106-aa4799ad84f5",
"requestTypeId": "d9b6cb37-7122-4e5a-8670-60b8c20c5acd",
"status": "COMPLETED"
}
}Request Rejection
If the process produces a validation error or is reviewed by a back-office operator and rejected, the system will send a KO event via webhook. Below is an example of the payload received:
{
"id": "297f861a-6bd5-4118-9af1-f39eae4bcc11",
"type": "STATUS_UPDATE",
"createdAt": "2025-06-17T07:41:41.513756032Z",
"request": {
"requestId": "d71a3020-553d-492f-a95e-9e210c8b35b1",
"requestTypeId": "48ade5f6-1dd1-4990-bcd9-a9e146bbae58",
"status": "CANCELLED"
}
}Gli status possibili in caso di KO sono: EXPIRED, FAILED, CANCELLED
Webhook Retry Mechanism
NOB webhooks implement an automatic retry mechanism with exponential backoff in case of failed delivery:
The initial waiting time between one attempt and the next is 300 ms.
The waiting time is doubled with each retry (2x multiplier).
The maximum waiting time between two consecutive attempts is 15 minutes.
Retries are performed for a total maximum period of 4 hours.
The exponential backoff is reset to the initial value only after 10 consecutive successful deliveries occur.