# Understanding webhooks 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.