The document preservation webhook allows you to programmatically learn when a document you uploaded through Lean Disposable has been successfully preserved (conservazione a norma).
Preservation is asynchronous: the document is accepted by the uploadDoc method, and a separate batch process submits it to the preservation system and later confirms completion. Without a webhook there is no way for your application to know when that happens.
To receive the notification, add the optional webhookUrl property to the uploadDoc request. Each uploaded document can be linked to a single webhook configuration.
Example:
{
"idOtp": 2587763,
"deviceCode": "PROVIDER1",
"externalKey": "CONTRACT-0001",
"file": "encoded base 64 file",
"extension": "pdf",
"typeDoc": "CONTRACT",
"webhookUrl": "https://example.com/callback"
}Check the webhook configuration page for the URL requirements and the signature verification procedure.
When the document is accepted, the uploadDoc API returns 200 (OK). The response is unchanged by this feature — supplying webhookUrl adds no field to it:
{
"deviceCode": "PROVIDER1",
"typeDoc": "CONTRACT",
"externalKey": "CONTRACT-0001",
"uploadDate": 1733496805136,
"filename": "3333217_a4ece4b3e9626ccfd3bac2eb77c0c1d7950be77e190a64fcf1957279e677ffc7.pdf"
}Correlate the later notification using the deviceCode you sent in the request, together with the externalKey if you supplied one. Both are echoed back in the notification payload.
No webhook notification is sent when the document is uploaded. The only notification is the one emitted when preservation completes.
Only successful preservation is notified — a FAILED state is never sent. No webhook is emitted while the document is still being processed, nor if a preservation attempt fails.
You do not need to handle preservation failures: when an attempt fails, Namirial takes the document in charge and works on it until it reaches the PRESERVED state, at which point the document.preserved notification is sent as usual. A failure therefore delays the notification, it does not cancel it.
The practical consequence is that the absence of a notification always means not preserved yet — either still in progress or being remediated on our side — and never give up and stop waiting.
If webhookUrl is omitted, no notification is ever produced for that document. Documents uploaded before this feature was released are not notified retroactively.
The system sends one notification when the document reaches the preserved state.
The system sends the notification as an HTTP POST request to your configured webhook URL.
Example:
{
"eventId": "0199a3f2-7c4e-7a1b-9d33-2f8c1e5b4a70",
"eventType": "document.preserved",
"occurredAt": "2026-08-17T09:12:44Z",
"externalKey": "CONTRACT-0001",
"deviceCode": "PROVIDER1",
"typeDoc": "CONTRACT",
"submissionId": "SUB-0000123",
"srId": "SR-0000456",
"aipId": "AIP-0000789",
"completedDate": "2026-08-17T09:10:02Z"
}The webhook contains the following info:
- eventId: Unique identifier of the notification. Use it as the idempotency key.
- eventType: Event type — always
document.preserved. - occurredAt: Date and time the notification was produced, in ISO 8601 format (e.g.
2026-08-17T09:12:44Z). - externalKey: The external reference you supplied in the
uploadDocrequest, if any. Use it, together withdeviceCode, to correlate the notification with your upload. - deviceCode: The device code of the disposable the document is linked to, exactly as supplied in the
uploadDocrequest. - typeDoc: Document type, as supplied at upload. Possible values:
IDENTIFICATION_DOC,CONTRACT,AUDIT_LOG,IDENTITY_ASSERTION. - submissionId: Identifier of the submission to the preservation system.
- srId: Identifier of the preservation report (rapporto di versamento).
- aipId: Identifier of the archival information package (AIP).
- completedDate: Date and time preservation completed, in ISO 8601 format.
The payload never carries document content, credentials, or any authentication factor.
Expected Response:
- HTTP status code:
200(OK) - Response timeout: 10 seconds
- Response body: Not required (ignored if present)
Only 200 is treated as success. A response of 202 or 204 — natural for asynchronous processing on your side — is treated as a failure and the notification is retried for the full 24-hour window. Answer 200 as soon as you have accepted the event, and process it afterwards.
Retry Behavior:
The system retries failed webhook deliveries using exponential backoff:
| Attempt | Wait Time | Cumulative Time |
|---|---|---|
| 1 | 1 second | 1 second |
| 2 | 2 seconds | 3 seconds |
| 3 | 4 seconds | 7 seconds |
| 4 | 8 seconds | 15 seconds |
| ... | ... | ... |
| Final | - | 24 hours max |
Retry Triggers:
- HTTP status codes: 4xx (except 400, 401, 403), 5xx
- Any 2xx other than 200, and any 3xx
- Network errors (timeout, connection refused, DNS failure)
- No response within 10 seconds
Not Retried:
- HTTP
400,401,403— the payload or the credentials were rejected, retrying changes nothing - The destination host is no longer allowlisted
Redirects are never followed: a 3xx response is a failed delivery.
After 24 Hours:
- Retries stop permanently
- Notification is marked as failed
- No further attempts are made
Handling Duplicate Notifications
Delivery is at-least-once: the same notification may be delivered more than once due to retries or network issues. Use the eventId field to detect and ignore duplicates:
{
"eventId": "0199a3f2-7c4e-7a1b-9d33-2f8c1e5b4a70", // Use this as idempotency key
"eventType": "document.preserved",
...
}The diagram below shows the preservation states of an uploaded document and the single transition for which Lean Disposable sends a notification. FAILED is an internal state: it is never notified, and Namirial remediates it until the document reaches PRESERVED.
Notification Timing Limitations.
The notification is emitted as soon as the preservation system confirms completion, but the time between upload and confirmation is not bounded by an SLA. Factors affecting it include:
- The batch submission cadence
- Processing time of the preservation system
- Remediation of a failed preservation attempt on the Namirial side
- Retry attempts on your endpoint