Gestire i webhook per gli eventi delle pratiche, a livello di pratica e a livello di organizzazione.
Avviso di deprecazione
Gli endpoint
webhook-subscriptionsono deprecati e saranno rimossi il 31 ottobre 2026:
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionGET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionDELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscriptionMigrare ai nuovi endpoint
webhooksdescritti di seguito prima di tale data. Dopo la rimozione, le chiamate ai vecchi endpoint non andranno a buon fine. Vedere Migrazione da webhook-subscription.
I webhook consentono alla propria applicazione di ricevere notifiche in tempo reale sugli eventi delle pratiche. Invece di interrogare ciclicamente l'API per gli aggiornamenti di stato, NSE invia un evento all'endpoint HTTPS indicato appena si verifica l'evento sottoscritto.
I webhook possono essere registrati a due livelli:
| Livello | Ambito | Eventi supportati |
|---|---|---|
| Pratica | Una singola pratica | Tutti gli eventi (vedere Eventi supportati) |
| Organizzazione | Tutte le pratiche dell'organizzazione | Solo EnvelopeCompleted |
Per entrambi i livelli si registra un URL webhook e si seleziona l'evento che deve attivarlo (ad esempio EnvelopeCompleted o RecipientRejected). Ogni webhook ha un proprio webhookId, da utilizzare per leggerlo, aggiornarlo o eliminarlo.
GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks
Restituisce tutti i webhook configurati per la pratica specificata.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
envelopeId | string (uuid) | Sì | Identificativo univoco della pratica |
POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks
Crea un webhook per la pratica specificata.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
envelopeId | string (uuid) | Sì | Identificativo univoco della pratica |
Content-Type: application/json
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
url | string | Sì | L'URL HTTPS su cui ricevere gli eventi webhook |
event | WebhookEventType (string) | Sì | L'evento che attiva il webhook. Vedere Eventi supportati |
authentication | WebhookAuthenticationRequest | No | Impostazioni di autenticazione per l'endpoint webhook |
| Evento | Descrizione |
|---|---|
EnvelopeSent | La pratica è stata inviata |
EnvelopeCompleted | La pratica è stata completata* |
EnvelopeCanceled | La pratica è stata annullata |
EnvelopeRestarted | La pratica è stata riavviata |
EnvelopeDeleted | La pratica è stata eliminata |
RecipientCompleted | Un destinatario ha completato la propria azione |
RecipientRejected | Un destinatario ha respinto la pratica |
RecipientDelegated | Un destinatario ha delegato la propria azione |
*Con la funzionalità EnrichedWebhook abilitata, l'evento EnvelopeCompleted restituisce dati aggiuntivi, ad esempio fasi, destinatari, artefatti e metadati della classe documentale.
| Campo | Tipo | Nullable | Descrizione |
|---|---|---|---|
headers | object (map<string, string>) | Sì | Header HTTP opzionali da includere nelle chiamate webhook, ad esempio un header Authorization |
clientCertificate | string | Sì | Certificato client opzionale codificato in PEM per mTLS |
clientKey | string | Sì | Chiave privata opzionale codificata in PEM per mTLS |
{
"url": "https://example.com/hooks/envelope",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}{
"type": "EnvelopeCompleted",
"id": "cf02da82-1234-1234-1234-f07c9fafb1d0",
"occurredAt": "2026-11-17T08:12:17.767+00:00",
"organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
"envelope": {
"id": "6af2128b-1234-1234-1234-881581c104c3",
"status": "Completed"
}
}{
"type": "EnvelopeCompleted",
"id": "7d84ac88-1234-1234-1234-faae948cfe07",
"occurredAt": "2026-11-17T08:16:44.947+00:00",
"organizationId": "afa1c381-1234-1234-1234-6e6796af7ff3",
"envelope": {
"id": "f2c3c35d-1234-1234-1234-2a882bca7e19",
"status": "Completed",
"name": "Contract for Mario Rossi",
"createdAt": "2026-11-17T08:15:49.637+00:00",
"sentAt": "2026-11-17T08:16:18.976+00:00",
"completedAt": "2026-11-17T08:16:42.701+00:00",
"stages": [
{
"id": "5d501c26-1234-1234-1234-cdcdc5918d52",
"name": "Stage3",
"sortOrder": 1,
"type": "Signer",
"requiredRecipientCompletions": 1,
"recipients": [
{
"id": "d92c57ca-1234-1234-1234-3931cc784a6e",
"givenName": "Mario",
"surname": "Rossi",
"email": "m.gierlinger@namirial.com",
"status": "Completed",
"completedAt": "2026-11-17T08:16:42.374+00:00"
}
]
},
{
"id": "dc1ab1b6-1234-1234-1234-3ed51f23904e",
"name": "",
"sortOrder": 2,
"type": "CarbonCopy",
"requiredRecipientCompletions": 0,
"recipients": [
{
"id": "d0965a53-1234-1234-1234-c88fc3db7f86",
"givenName": "Mario",
"surname": "Rossi",
"email": "m.rossi@sample.com",
"status": "Completed",
"completedAt": "2026-11-17T08:16:42.701+00:00"
}
]
}
],
"artifacts": [
{
"id": "cfe314d5-1234-1234-1234-24c974923fe5",
"type": "CompletedFile",
"name": "A.pdf",
"fileId": "662806f3-1234-1234-1234-539c12ef097c",
"downloadLink": {
"url": "https://"
}
},
{
"id": "314676fd-1234-1234-1234-edfec12150ba",
"type": "AuditTrail",
"name": "Audit Trail.pdf",
"downloadLink": {
"url": "https://"
}
}
]
}
}GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}
Restituisce il webhook specificato.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
envelopeId | string (uuid) | Sì | Identificativo univoco della pratica |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
PUT /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}
Aggiorna il webhook specificato. Il corpo della richiesta (UpdateEnvelopeWebhookRequest) ha la stessa struttura di Creare un webhook della pratica: url ed event sono obbligatori, authentication è facoltativo.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
envelopeId | string (uuid) | Sì | Identificativo univoco della pratica |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
{
"url": "https://example.com/hooks/envelope-new",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}
Elimina il webhook specificato.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
envelopeId | string (uuid) | Sì | Identificativo univoco della pratica |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
I webhook dell'organizzazione vengono attivati per l'evento corrispondente su tutte le pratiche dell'organizzazione, quindi non è necessario registrare un webhook per ogni pratica.
Nota
I webhook dell'organizzazione supportano solo l'evento
EnvelopeCompleted. I webhook della pratica supportano tutti gli eventi elencati in Eventi supportati.
Le strutture di richiesta e di payload sono le stesse dei webhook della pratica. Vedere WebhookAuthenticationRequest e gli esempi di payload riportati sopra. La funzionalità EnrichedWebhook si applica anche ai webhook dell'organizzazione.
GET /api/v1/organizations/{organizationId}/webhooks
Restituisce tutti i webhook configurati per l'organizzazione specificata.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
POST /api/v1/organizations/{organizationId}/webhooks
Crea un nuovo webhook per l'organizzazione specificata. È supportato solo l'evento EnvelopeCompleted.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
Content-Type: application/json
Corpo della richiesta (CreateOrganizationWebhookRequest) per la creazione di un webhook dell'organizzazione.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
url | string | Sì | L'URL HTTPS su cui ricevere gli eventi webhook |
event | WebhookEventType (string) | Sì | L'evento che attiva il webhook. Per i webhook dell'organizzazione è supportato solo EnvelopeCompleted |
authentication | WebhookAuthenticationRequest | No | Impostazioni di autenticazione per l'endpoint webhook |
{
"url": "https://example.com/hooks/organization",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}GET /api/v1/organizations/{organizationId}/webhooks/{webhookId}
Restituisce il webhook dell'organizzazione specificato.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
PUT /api/v1/organizations/{organizationId}/webhooks/{webhookId}
Aggiorna il webhook dell'organizzazione specificato. Il corpo della richiesta ha la stessa struttura di Creare un webhook dell'organizzazione: url ed event sono obbligatori, authentication è facoltativo.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
{
"url": "https://example.com/hooks/organization-new",
"event": "EnvelopeCompleted",
"authentication": {
"headers": {
"Authorization": "Bearer token_123"
}
}
}DELETE /api/v1/organizations/{organizationId}/webhooks/{webhookId}
Elimina il webhook dell'organizzazione specificato.
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
organizationId | string (uuid) | Sì | Identificativo univoco dell'organizzazione |
webhookId | string (uuid) | Sì | Identificativo univoco del webhook |
I precedenti endpoint webhook-subscription sono deprecati e saranno rimossi il 31 ottobre 2026. Per eseguire la migrazione:
| Endpoint deprecato | Sostituzione |
|---|---|
POST .../envelopes/{envelopeId}/webhook-subscription | POST .../envelopes/{envelopeId}/webhooks (il campo event è ora obbligatorio) |
GET .../envelopes/{envelopeId}/webhook-subscription | GET .../envelopes/{envelopeId}/webhooks oppure GET .../envelopes/{envelopeId}/webhooks/{webhookId} |
DELETE .../envelopes/{envelopeId}/webhook-subscription | DELETE .../envelopes/{envelopeId}/webhooks/{webhookId} |
Modifiche da tenere presenti:
- Le richieste richiedono ora il campo
event. - I webhook sono identificati da un
webhookId, necessario per recuperare, aggiornare o eliminare un singolo webhook. - I webhook possono ora essere aggiornati con
PUT, senza doverli eliminare e ricreare.