Vai al contenuto

Webhook

Gestire i webhook per gli eventi delle pratiche, a livello di pratica e a livello di organizzazione.


Avviso di deprecazione

Gli endpoint webhook-subscription sono deprecati e saranno rimossi il 31 ottobre 2026:

  • POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription
  • GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription
  • DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhook-subscription

Migrare ai nuovi endpoint webhooks descritti 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:

LivelloAmbitoEventi supportati
PraticaUna singola praticaTutti gli eventi (vedere Eventi supportati)
OrganizzazioneTutte le pratiche dell'organizzazioneSolo 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.


Webhook della pratica

Elencare i webhook di una pratica

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks

Restituisce tutti i webhook configurati per la pratica specificata.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
envelopeIdstring (uuid)SìIdentificativo univoco della pratica

Creare un webhook della pratica

POST /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks

Crea un webhook per la pratica specificata.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
envelopeIdstring (uuid)SìIdentificativo univoco della pratica

Corpo della richiesta

Content-Type: application/json

CampoTipoObbligatorioDescrizione
urlstringSìL'URL HTTPS su cui ricevere gli eventi webhook
eventWebhookEventType (string)SìL'evento che attiva il webhook. Vedere Eventi supportati
authenticationWebhookAuthenticationRequestNoImpostazioni di autenticazione per l'endpoint webhook

Eventi supportati

EventoDescrizione
EnvelopeSentLa pratica è stata inviata
EnvelopeCompletedLa pratica è stata completata*
EnvelopeCanceledLa pratica è stata annullata
EnvelopeRestartedLa pratica è stata riavviata
EnvelopeDeletedLa pratica è stata eliminata
RecipientCompletedUn destinatario ha completato la propria azione
RecipientRejectedUn destinatario ha respinto la pratica
RecipientDelegatedUn 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.

WebhookAuthenticationRequest

CampoTipoNullableDescrizione
headersobject (map<string, string>)SìHeader HTTP opzionali da includere nelle chiamate webhook, ad esempio un header Authorization
clientCertificatestringSìCertificato client opzionale codificato in PEM per mTLS
clientKeystringSìChiave privata opzionale codificata in PEM per mTLS

Esempio di richiesta

{
  "url": "https://example.com/hooks/envelope",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Esempio di payload - pratica completata (senza la funzionalità EnrichedWebhook)

{
  "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"
  }
}

Esempio di payload - pratica completata (con la funzionalità EnrichedWebhook)

{
  "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://"
        }
      }
    ]
  }
}

Recuperare un webhook della pratica

GET /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}

Restituisce il webhook specificato.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
envelopeIdstring (uuid)SìIdentificativo univoco della pratica
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Aggiornare un webhook della pratica

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.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
envelopeIdstring (uuid)SìIdentificativo univoco della pratica
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Esempio di richiesta

{
  "url": "https://example.com/hooks/envelope-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Eliminare un webhook della pratica

DELETE /api/v1/organizations/{organizationId}/envelopes/{envelopeId}/webhooks/{webhookId}

Elimina il webhook specificato.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
envelopeIdstring (uuid)SìIdentificativo univoco della pratica
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Webhook dell'organizzazione

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.

Elencare i webhook dell'organizzazione

GET /api/v1/organizations/{organizationId}/webhooks

Restituisce tutti i webhook configurati per l'organizzazione specificata.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione

Creare un webhook dell'organizzazione

POST /api/v1/organizations/{organizationId}/webhooks

Crea un nuovo webhook per l'organizzazione specificata. È supportato solo l'evento EnvelopeCompleted.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione

Corpo della richiesta

Content-Type: application/json

Corpo della richiesta (CreateOrganizationWebhookRequest) per la creazione di un webhook dell'organizzazione.

CampoTipoObbligatorioDescrizione
urlstringSìL'URL HTTPS su cui ricevere gli eventi webhook
eventWebhookEventType (string)SìL'evento che attiva il webhook. Per i webhook dell'organizzazione è supportato solo EnvelopeCompleted
authenticationWebhookAuthenticationRequestNoImpostazioni di autenticazione per l'endpoint webhook

Esempio di richiesta

{
  "url": "https://example.com/hooks/organization",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Recuperare un webhook dell'organizzazione

GET /api/v1/organizations/{organizationId}/webhooks/{webhookId}

Restituisce il webhook dell'organizzazione specificato.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Aggiornare un webhook dell'organizzazione

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.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Esempio di richiesta

{
  "url": "https://example.com/hooks/organization-new",
  "event": "EnvelopeCompleted",
  "authentication": {
    "headers": {
      "Authorization": "Bearer token_123"
    }
  }
}

Eliminare un webhook dell'organizzazione

DELETE /api/v1/organizations/{organizationId}/webhooks/{webhookId}

Elimina il webhook dell'organizzazione specificato.

Parametri di percorso

NomeTipoObbligatorioDescrizione
organizationIdstring (uuid)SìIdentificativo univoco dell'organizzazione
webhookIdstring (uuid)SìIdentificativo univoco del webhook

Migrazione da webhook-subscription

I precedenti endpoint webhook-subscription sono deprecati e saranno rimossi il 31 ottobre 2026. Per eseguire la migrazione:

Endpoint deprecatoSostituzione
POST .../envelopes/{envelopeId}/webhook-subscriptionPOST .../envelopes/{envelopeId}/webhooks (il campo event è ora obbligatorio)
GET .../envelopes/{envelopeId}/webhook-subscriptionGET .../envelopes/{envelopeId}/webhooks oppure GET .../envelopes/{envelopeId}/webhooks/{webhookId}
DELETE .../envelopes/{envelopeId}/webhook-subscriptionDELETE .../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.