Configurare i webhook

Panoramica

Un webhook è una richiamata HTTPS definita dall'utente che viene attivata quando si verifica un particolare evento nel sito di origine (Adobe Acrobat Sign in questo caso).

In effetti, un webhook non è altro che un servizio Web che accetta le richieste HTTPS POST da una fonte. Quindi, un webhook è un servizio REST che accetta dati o flussi di dati.

I webhook sono utilizzati nella comunicazione servizio a servizio in un Modello push.

Quando si verifica un evento trigger, Acrobat Sign crea un POST HTTPS con un corpo JSON e lo invia all'URL specificato.

 

I webhook offrono numerosi vantaggi rispetto al precedente metodo di richiamata, alcuni dei quali sono:

  • Gli amministratori possono abilitare i propri webhook senza dover coinvolgere il supporto di Acrobat Sign per inserire l’URL di richiamata
  • I webhook sono migliori in termini di “freschezza”, efficienza della comunicazione e sicurezza dei dati. Nessuna votazione richiesta
  • I webhook consentono facilmente diversi livelli di ambito (Account/Gruppo/Utente/Risorsa). 
  • I webhook sono una soluzione API più moderna, che consente una configurazione più semplice per applicazioni moderne
  • È possibile configurare più webhook per ambito (Account/Gruppo/Utente/Risorsa) con specifici callback
  • I webhook consentono di restituire la selezione dei dati, dove i callback sono una soluzione “tutto o niente”;
  • È possibile configurare i metadati trasportati con un webhook (di base o dettagliato)
  • I webhook sono molto più facili da creare, modificare o disabilitare in base alle esigenze, poiché l’interfaccia utente è interamente sotto il controllo dell’amministratore.
Nota:

Questo documento è incentrato principalmente sull’interfaccia utente dei webhook nell’applicazione web Acrobat Sign (in precedenza Adobe Sign).

Gli sviluppatori alla ricerca di dettagli API possono trovare ulteriori informazioni qui:


Come utilizzare questa funzione

Gli amministratori dovranno prima disporre di un servizio webhook, in grado di accettare il push in entrata da Acrobat Sign. In merito, ci sono numerose opzioni e fino a quando il servizio può accettare richieste POST e GET, il webhook andrà a buon fine.

Una volta installato il servizio, un amministratore di Acrobat Sign può creare un nuovo webhook dall'interfaccia Webhook nel menu Account del sito Acrobat Sign.

Gli amministratori possono configurare il webhook per attivare gli eventi Accordo, Moduli Web o Invio in modalità collettiva.

L’ambito del webhook può includere l’intero account o i singoli gruppi tramite l’interfaccia di amministrazione. Gli ambiti Utente e Risorsa sono possibili anche tramite l’API

Il tipo di dati che viene inviato all’URL è configurabile e può includere informazioni sull’accordo, sulle informazioni sul partecipante, sul documento firmato e così via.

Una volta configurato e salvato il webhook, Acrobat Sign invia un nuovo oggetto JSON all’URL definito ogni volta che l’evento trigger viene bloccato. Non è necessaria alcuna modifica in corso del webhook, a meno che non si desideri modificare i criteri di attivazione dell’evento o il payload JSON.


Verifica dell’intento dell’URL del webhook

Prima di registrare un webhook, Acrobat Sign verifica che l’URL del webhook indicato nella richiesta di registrazione sia effettivamente in grado di ricevere notifiche. A questo scopo, quando Acrobat Sign riceve una nuova richiesta di registrazione del webhook, inizialmente effettua una richiesta di verifica all’URL del webhook. Questa richiesta di verifica è un GET HTTPS inviato all'URL del webhook. Questa richiesta ha un'intestazione HTTP personalizzata X-AdobeSign-ClientId. Il valore in questa intestazione viene impostato sull'ID client (ID applicazione) dell'applicazione API che richiede di creare/registrare il webhook. Per registrare correttamente un webhook, il suo URL deve rispondere a questa richiesta di verifica con un codice di risposta 2XX; inoltre, può restituire lo stesso valore di ID client in uno dei due modi seguenti:

  • In un’intestazione di risposta X-AdobeSign-ClientId. Si tratta della stessa intestazione trasmessa nella richiesta, inclusa anche nella risposta.
  • Oppure nel corpo della risposta JSON con chiave X-AdobeSign-ClientId. Il suo valore corrisponde all’ID client inviato nella richiesta.

Il webhook sarà registrato correttamente solo su risposta corretta (codice di risposta 2XX) e convalida dell'id client sia nell'intestazione che nel corpo della risposta. Lo scopo di questa richiesta di verifica è dimostrare che l’URL del webhook desidera effettivamente ricevere notifiche su tale URL. Se hai inserito involontariamente l’URL errato, questo non risponderà correttamente alla verifica della richiesta di intento e Acrobat Sign non invierà alcuna notifica a tale URL. Inoltre, l'URL del webhook può anche convalidare la ricezione di notifiche solo attraverso i webhook registrati da una specifica applicazione. Questo può essere fatto convalidando l'ID client dell'applicazione approvata nell'intestazione X-AdobeSign-ClientId. Se l’URL del webhook non riconosce l’ID client, NON DEVE rispondere con il codice di risposta positivo e Acrobat Sign farà in modo che l’URL non sia registrato come webhook.

La verifica della chiamata all’URL del webhook verrà effettuata nei seguenti casi:

  • Registrazione webhook - Se la verifica della chiamata all’URL del webhook ha esito negativo, il webhook non verrà creato
  • Aggiornamento di webhook: DA INATTIVO A ATTIVO: se la verifica della chiamata all’URL del webhook ha esito negativo, lo stato del webhook non verrà modificato in ATTIVO

Come rispondere a una notifica webhook

Acrobat Sign esegue una verifica implicita dell’intento in ogni richiesta di notifica webhook inviata all’URL webhook. Pertanto, ogni richiesta HTTPS di notifica webhook contiene anche l’intestazione HTTP personalizzata X-AdobeSign-ClientId. Il valore di questa intestazione è l’ID client (ID applicazione) dell’applicazione che ha creato il webhook. Considereremo l’avvenuto recapito della notifica webhook se, e solo se, viene restituita una risposta di esito positivo (codice di risposta 2XX) e viene inviato l’id client nell’intestazione HTTP (X-AdobeSign-ClientId)  oppure in un corpo della risposta JSON con la chiave xAdobeSignClientId e con il valore dello stesso ID client. In caso contrario, riproveremo a inviare la notifica all’URL del webhook fino a quando non saranno esauriti i tentativi.

Come indicato in precedenza, il valore dell’intestazione 'X-AdobeSign-ClientId' che è inclusa in ogni richiesta di notifica da Sign (id client) deve essere ripetuto in una delle seguenti modalità:

1. Intestazione HTTP X-AdobeSign-ClientId e lo stesso valore di questo ID client

Esempio di codice Javascript per recuperare l’ID client, convalidarlo e quindi restituirlo nell’intestazione della risposta

// Recupero id client

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

//Esegui convalida

if (clientid ==="BGBQIIE7H253K6") //sostituisci 'BGBQIIE7H253K6' con l’id client dell’applicazione con cui si crea il webhook

{

    //Restituisce nell’intestazione della risposta

    response.headers['X-AdobeSign-ClientId'] = clientid;

    response.status = 200;  // valore predefinito

}

Esempio di codice PHP per recuperare l’ID client, convalidarlo e restituirlo nell’intestazione della risposta

 

<?php

// Recupero id client

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Esegui convalida

if($clientid == "BGBQIIE7H253K6") //sostituisci 'BGBQIIE7H253K6' con l’ID client dell’applicazione con cui si crea il webhook

{

    //Restituisce nell’intestazione della risposta

   header("X-AdobeSign-ClientId:$clientid");

   header("HTTP/1.1 200 OK"); // valore predefinito

}

?>

 


2. Il corpo della risposta JSON con chiave xAdobeSignClientId e con lo stesso valore dell’ID client

Esempio di codice Javascript per recuperare l’ID client, convalidarlo e restituirlo nel corpo della risposta

// Recupero id client

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

 

//Esegui convalida

if (clientid ==="BGBQIIE7H253K6") //sostituisci 'BGBQIIE7H253K6' con l’id client dell’applicazione con cui si crea il webhook

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Restituisce l’ID client nel corpo

                       };

    response.headers['Content-Type'] = 'application/json';

    response.body = responseBody;

    response.status = 200;

}

Esempio di codice PHP per recuperare l’ID client, convalidarlo e restituirlo nel corpo della risposta

<?php

// Recupero id client

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Esegui convalida

if($clientid == "BGBQIIE7H253K6") //sostituisci 'BGBQIIE7H253K6' con l’ID client dell’applicazione con cui si crea il webhook

{

   //Restituisce nel corpo della risposta

   header("Content-Type: application/json");

   $body = array('xAdobeSignClientId' => $clientid);

   echo json_encode($body);

   header("HTTP/1.1 200 OK"); // valore predefinito

}

?>

Esempio di corpo JSON della risposta

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Prerequisiti

Avrai bisogno di:

  1. Un account Microsoft con licenza per la creazione di applicazioni di Funzioni di Azure
  2. Un’applicazione di Funzioni di Azure esistente: puoi crearne una visitando https://docs.microsoft.com/it-it/azure/azure-functions/functions-create-first-azure-function 
  3. Conoscenza di base di JavaScript, per comprendere e scrivere il codice in qualsiasi lingua


Procedura per creare un trigger di Funzioni di Azure che funga da webhook di Acrobat Sign

Per creare una funzione trigger HTTP Javascript:

1. Accedi tramite il tuo account Microsoft https://portal.azure.com/

2. Apri l’applicazione di Funzioni di Azure visualizzata nella scheda App per le funzioni.

Si apre l’elenco delle applicazioni di Funzioni di Azure:

3. Scegli l’applicazione in cui creare la nuova funzione

4. Per creare una nuova funzione di Azure, fai clic sul pulsante Crea (+)

 

5. Seleziona Webhook e API come scenario e Javascript come lingua

6. Fai clic su Creare questa funzione

Viene creata una nuova funzione che ha la capacità di gestire una richiesta API in ingresso.


Aggiungere la logica per registrare il webhook di Acrobat Sign

Prima di registrare un webhook, Acrobat Sign verifica che l’URL del webhook indicato nella richiesta di registrazione sia effettivamente in grado di ricevere notifiche. A questo scopo, quando Acrobat Sign riceve una nuova richiesta di registrazione del webhook, inizialmente effettua una richiesta di verifica all’URL del webhook. Questa richiesta di verifica è del tipo GET HTTPS e viene inviata all’URL del webhook con un’intestazione HTTP personalizzata X-AdobeSign-ClientId. In questa intestazione, il valore viene impostato sull’ID client dell’applicazione che richiede di creare/registrare il webhook. Per registrare un webhook, l’URL corrispondente deve rispondere a questa richiesta di verifica con un codice di risposta 2XX. Inoltre, l’URL può restituire lo stesso valore dell’ID client con una delle seguenti modalità.

Sono disponibili due opzioni:


Opzione 1: passare l’ID client a X-AdobeSign-ClientId come intestazione della risposta

Passare X-AdobeSign-ClientId nell’intestazione della risposta. Si tratta della stessa intestazione trasmessa nella richiesta, che viene ripetuta nella risposta.

Sostituisci il file Index.js con il seguente snippet di codice:

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Verifica che il ClientID in ingresso sia autentico

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* Il valore predefinito è 200 */ // qualsiasi risposta 2XX è accettabile

            body: "Notifica accettata",

            headers : {

                'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Chiamata illegittima identificata"

        };

    }

    context.done();

};

 

Verifica il comportamento eseguendo una richiesta fittizia:

1. Fai clic sul pulsante Test nell’angolo all’estrema destra

2. Esegui la richiesta fittizia

Anche se le intestazioni della risposta non sono visualizzate in alto, puoi osservarle in modo fittizio tramite postman/DHC o qualsiasi altro servizio.


Opzione 2: passa l’ID client nel corpo della risposta con la chiave xAdobeSignClientId

Nel corpo della risposta JSON con la chiave xAdobeSignClientId e con lo stesso valore dell’ID client che è stato inviato nella richiesta.

Sostituisci il file Index.js con il seguente snippet di codice:

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Verifica che il ClientID in ingresso sia autentico

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* Il valore predefinito è 200 */ // qualsiasi risposta 2XX è accettabile

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Chiamata illegittima identificata"

        };

    }

    context.done();

};

 

Verifica il comportamento eseguendo una richiesta fittizia

1. Fai clic sul pulsante Test nell’angolo all’estrema destra

2. Esegui la richiesta fittizia

Nota che è previsto lo stesso comportamento di clientID quando l’URL Webhook riceve le notifiche POST. 


Pronto all’uso

Una volta verificato il comportamento, l’URL di webhook funziona in base agli standard di Acrobat Sign. Puoi aggiornare ulteriormente la logica personalizzata in base alle tue esigenze.

 

Ottenere l’URL della funzione

  • Fai clic su Ottieni URL funzione

 

Copia l’URL e utilizzalo per creare webhook in Acrobat Sign.

Creazione della funzione AWS Lambda

Per creare una funzione AWS Lambda, accedi alla Console di gestione AWS e seleziona il servizio AWS Lambda dall’elenco dei servizi.

  • Fai clic sull’opzione Create a Lambda function using "Author From Scratch" 
  • Nella pagina Configure function, inserisci il nome funzione “lambdaWebhooks” e seleziona Node.js 4.3 come runtime
  • Per Role, scegli un ruolo esistente o creane uno nuovo dai modelli
    • Se hai scelto  Create new role from template(s), inserisci un nome di ruolo (ad es. role-lambda) e seleziona Simple Microservices permissions dall’elenco Policy templates 
  • Fai clic sul pulsante Create function

  • Nella nuova pagina della funzione AWS lambda, seleziona “Edit code inline” come “Code entry type”, mantieni index.handler come handler.
  • Aggiungere la logica per registrare il webhook di Acrobat Sign

    Prima di registrare un webhook, Acrobat Sign verifica che l’URL del webhook indicato nella richiesta di registrazione sia effettivamente in grado di ricevere notifiche. A questo scopo, quando Acrobat Sign riceve una nuova richiesta di registrazione del webhook, inizialmente effettua una richiesta di verifica all’URL del webhook. Questa richiesta di verifica è del tipo GET HTTPS e viene inviata all’URL del webhook con un’intestazione HTTP personalizzata X-AdobeSign-ClientId. In questa intestazione, il valore viene impostato sull’ID client dell’applicazione che richiede di creare/registrare il webhook. Per registrare correttamente un webhook, l’URL relativo deve rispondere a questa richiesta di verifica con un codice di risposta 2XX E deve restituire lo stesso valore di ID client in uno dei due modi seguenti. Nota inoltre che è previsto lo stesso comportamento per clientID quando l’URL Webhook riceve le notifiche POST. 

    Segui uno dei due casi:

    Caso 1: passa l’ID client a X-AdobeSign-ClientId come intestazione della risposta

    •  Passa X-AdobeSign-ClientId nell’intestazione della risposta. Si tratta della stessa intestazione trasmessa nella richiesta, che viene ripetuta nella risposta.

      Snippet di codice
      Nel file index.js, sostituisci lo snippet di codice generato automaticamente con il codice seguente:

Esempio di codice JS del nodo per recuperare l’ID client, convalidarlo e quindi restituirlo nell’intestazione della risposta

exports.handler = function index(event, context, callback) {

  // Recupero id client

  var clientid = event.headers['X-AdobeSign-ClientId'];

 

  //Esegui convalida

  if (clientid =="BGBQIIE7H253K6") //Sostituisci 'BGBQIIE7H253K6' con l’ID client dell’applicazione con cui si crea il webhook

  {

    var response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! chiamata illegittima");

  }

}

 

Caso 2: passare l’ID client nel corpo della risposta con la chiave xAdobeSignClientId

Nel corpo della risposta JSON con la chiave xAdobeSignClientId e il valore relativo corrisponde all’ID client inviato nella richiesta dell’intestazione.

 

Snippet di codice

Sostituisci il file Index.js con quanto segue:

Esempio di codice JS del nodo per recuperare l’ID client, convalidarlo e quindi restituirlo nell’intestazione della risposta

exports.handler = function index(event, context, callback) {

 // Recupero id client

 var clientid = event.headers['X-AdobeSign-ClientId'];

  

 //Esegui convalida

 if (clientid =="BGBQIIE7H253K6") //Sostituisci 'BGBQIIE7H253K6' con l’ID client dell’applicazione con cui si crea il webhook

 {

   var responseBody = {

        xAdobeSignClientId : clientid

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Oops!! chiamata illegittima");

  }

}

  • Salva la funzione. È stata creata la funzione Lambda e siamo quasi pronti a utilizzarla in un webhook in tempo reale.

 

Configurazione dell’API Gateway di AWS

Per rendere questo modulo pubblicamente accessibile tramite metodo HTTP, è necessario configurare API Gateway di AWS utilizzando la funzione precedentemente creata come backend per l’API.

Nella Console di gestione AWS, seleziona la proprietà API Gateway dai servizi AWS e fai clic sul pulsante Create API.

  • Nella pagina Create new API, seleziona New API; quindi, in Name API, inserisci webhooks.
  • Fai clic sul pulsante Create API.
  • Dall’elenco a discesa Actions, seleziona l’opzione Create Resource.
  • Verifica l’opzione Configure as proxy resource e inserisci validate come Resource Name e {proxy+} in Resource Path.
  • Lascia deselezionata l’opzione Enable API Gateway CORS e fai clic sul pulsante Create Resource.
  • Mantieni selezionato Lambda Function Proxy come Integration type e, dall’elenco a discesa Lambda region, scegli l’area in cui è stata creata la funzione Lambda. Probabilmente si tratta della stessa area in cui stai creando API Gateway.
  • Inserisci validate nel campo Lambda Function, quindi fai clic sul pulsante Save.
  • Nella finestra a comparsa Add Permission to Lambda Function, seleziona OK.

Se tutti i passaggi precedenti sono stati eseguiti correttamente, verrà visualizzato qualcosa di questo tipo:

Implementare l’API

Il passaggio successivo prevede l’implementazione di questa API per renderla pronta all’utilizzo.

  • Nell’elenco a discesa Actions, seleziona Deploy API.
  • In Deployment stage, seleziona [New Stage]; quindi, in Stage name, inserisci prod (o un eventuale altro nome con cui desideri identificare questa fase).
  • Fai clic sul pulsante Deploy.

L’API è ora pronta per l’uso e il relativo URL di chiamata è riportato nella casella blu di seguito visualizzata:

Prendi nota di questo URL, perché dovrai inserirlo come URL di webhook in tempo reale.

 

Pronto all’uso

La procedura è terminata. Utilizza l’URL di cui sopra con “/{nodeJSfunctionName}” aggiunto come URL webhook nella richiesta API POST /webhooks.  Una volta verificato il comportamento, l’URL del webhook funziona come da
standard di Acrobat Sign. Puoi aggiornare o aggiungere ulteriormente la logica di personalizzazione in base alle tue esigenze.


Opzioni di configurazione

La configurazione del webhook richiede la definizione di cinque elementi:

  • Nome: scegli un nome intuitivo che gli altri amministratori possano riconoscere facilmente.
  • Ambito: ampiezza della rete che deve essere coperta dal webhook. Nell’interfaccia sono disponibili gli ambiti Account e Gruppo.
    • L’API supporta gli ambiti: Account, Gruppo, Utente e Risorsa.
    • È possibile definire un solo ambito per webhook.
  • URL: URL di destinazione a cui Acrobat Sign ha trasmesso il payload JSON.
  • Eventi: trigger in risposta al quale Acrobat Sign genera il codice JSON e lo trasmette all’URL.
    • Ogni evento crea un payload diverso relativo all’evento trigger.
    • In un webhook si possono includere più Eventi.
  • Parametri di notifica: la proprietà Parametri di notifica identifica le sezioni del payload dell’evento JSON, consentendoti di selezionare solo le sezioni dell’evento che sono importanti per questo webhook, riducendo in tal modo i dati non necessari all’URL.

 

Una volta definito il webhook, fai clic su Salva: il nuovo webhook inizierà subito a reagire agli eventi trigger. 

Nota:

Configura l’URL del webhook affinché risponda alle richieste di verifica e notifica del webhook in base al protocollo di verifica descritto in precedenza. L’ID client (ID applicazione) che verrà inviato ai webhook creati dall’applicazione Web Acrobat Sign sarà - UB7E5BXCXY

Configurare il webhook


Ambiti

  • Account: tutti gli eventi di abbonamento che si verificano nell’account attivano il push. 
    • Gli amministratori degli account possono visualizzare tutti i webhook definiti per l’account e per tutti i gruppi.
  • Gruppo: tutti gli eventi di abbonamento che si verificano in quel gruppo attivano il push. I webhook con ambito di gruppo esistono solo in un gruppo.
    • Gli amministratori dei gruppi possono visualizzare solo i webhook del proprio gruppo. Non possono visualizzare i webhook a livello di account o associati ad altri gruppi.
    • Gli account per i quali è attivata l’opzione Utenti in più gruppi visualizzeranno l’opzione per impostare il gruppo a cui deve essere applicato l’ambito.
  • Account utente: tutti gli eventi di abbonamento per un account utente attivano il push. I webhook a livello di utente possono essere creati solo tramite API.
  • Webhook a livello di risorsa: verrà creato per una risorsa specifica. Gli eventi specifici di questa risorsa verranno inviati all’URL del webhook. I webhook basati su risorse possono essere creati solo tramite API.


URL

Un URL webhook è un server che intercetta i messaggi di notifica HTTPS POST in entrata che vengono attivati quando si verificano eventi.

Per iscriversi al webhook degli eventi, è necessario questo URL.

  • Il client deve includere un URL HTTPS dove Acrobat Sign può POST. Questo URL deve essere disponibile su Internet.  
    • Ad esempio, gli URI 127.0.0.1 e localhost non funzioneranno.
    • L'endpoint URL deve essere in ascolto sulla porta 443.
  • Assicurati che il webhook supporti le richieste POST per le notifiche degli eventi in arrivo e le richieste GET per la richiesta di verifica.
  • L'URL non deve essere bloccato da un firewall.


Eventi

Di seguito sono riportati gli eventi che possono attivare un push all'URL del webhook, raggruppati per l'oggetto.

Ogni evento ha un modello del payload JSON che può essere inviato. (Fai clic sul nome dell'evento per visualizzare i dettagli del payload):

  • Invia in modalità collettiva (In precedenza Mega Sign): gli eventi Invia in modalità collettiva riguardano solo la creazione dell’oggetto principale Invia in modalità collettiva. Gli accordi secondari risultanti vengono registrati come eventi accordo.  
    • Invia in modalità collettiva - Tutti gli eventi: sono inclusi tutti gli eventi Invia in modalità collettiva. Se in futuro verranno definiti altri eventi, questi verranno automaticamente inclusi in questa impostazione.  Il payload JSON si basa sul singolo evento che viene attivato
    • Invio in modalità collettiva creato: quando viene creato un Invio in modalità collettiva
    • Invio in modalità collettiva condiviso: quando viene condiviso un Invio in modalità collettiva
    • Invio in modalità collettiva richiamato: quando viene richiamato un Invio in modalità collettiva
  • Modulo Web (in precedenza Widget): gli eventi per moduli Web riguardano solo la creazione del modello di modulo Web. Gli accordi secondari risultanti vengono registrati come eventi accordo.
    • Widget - Tutti gli eventi: sono inclusi tutti gli eventi modulo Web. Se in futuro verranno definiti altri eventi, questi verranno automaticamente inclusi in questa impostazione.  Il payload JSON si basa sul singolo evento che viene attivato
    • Widget creato: quando viene creato un modulo Web
    • Widget abilitato: quando viene abilitato un modulo Web
    • Widget disabilitato: quando viene disattivato un modulo Web
    • Widget modificato: quando viene modificato un modulo Web
    • Widget condiviso: quando un modulo Web viene condiviso
    • Creazione widget non riuscita: quando un modulo Web viene annullato automaticamente a causa di un problema di conversione


Parametri di notifica

I parametri di notifica consentono di personalizzare il payload JSON solo per elementi specifici dell’evento.

Ad esempio, in un evento Partecipante all’accordo sostituito, è possibile richiedere solo le proprietà Informazioni accordo e Informazioni partecipante, lasciando fuori Informazioni documento, e riducendo il volume totale nell’URL del webhook

 

  • Accordo
    • Informazioni accordo: informazioni dettagliate in base allo stato dell’accordo al momento dell’evento di attivazione
    • Informazioni documento accordo: include tutte le informazioni sul documento generate a seguito dell’evento
    • Informazioni sul partecipante all’accordo: include le informazioni sui partecipanti risultanti dall’evento
    • Documento accordo firmato: fornisce il PDF firmato. 
      • Applicabile agli eventi Flusso di lavoro degli accordi completato Tutti gli accordi
  • Invia in modalità collettiva
    • Invia in modalità collettiva: informazioni dettagliate sull’oggetto Invia in modalità collettiva che ha attivato l’evento
  • Modulo web
    • Widget informazioni: informazioni dettagliate sul modulo web che ha attivato l’evento
    • Widget informazioni documento: informazioni sul documento associate al modello di modulo web
    • Widget informazioni partecipante: informazioni sui partecipanti definiti nel modello di modulo web


Autenticazione SSL bidirezionale

L’SSL bidirezionale, spesso chiamato Client-Side SSL, o TLS reciproco, è una modalità SSL in cui sia il server che il client (browser Web) emettono certificati per identificare se stessi.

Gli amministratori dell’account possono configurare un certificato lato client sulla pagina Impostazioni di sicurezza.

Acrobat Sign verifica i certificati SSL durante la distribuzione dei payload nell’URL del webhook. I webhook che non superano la verifica del certificato SSL non consegnano correttamente il payload JSON. 

Utilizza l’SSL bidirezionale per autenticare il client (Acrobat Sign) e il servizio di ascolto per garantire che solo Acrobat Sign possa raggiungere l’URL del webhook. 

Se è stato creato da un’applicazione partner, il webhook utilizzerà un certificato client (se disponibile) dall’account di tale applicazione per identificarsi quando effettua le chiamate al webhook.

Di seguito sono riportate le domande più comuni relative sia al processo di verifica del server Web che alla verifica della certificazione client.

Verifica del server Web

Durante la registrazione di un webhook, Acrobat Sign verifica l’URL del server webhook.

I clienti non potranno registrare il webhook se la connessione all’URL di richiamata del webhook non può essere completata da Acrobat Sign.

No.

L'URL di callback del webhook può essere solo HTTPS sulla porta 443.

Acrobat Sign blocca il traffico HTTPS in uscita verso tuttele altri porte.

Un buon modo per verificare il certificato del server consiste nell'utilizzare il metodo Strumento di diagnostica di installazione DigiCert® SSL.

Inserisci solo il nome host, ad esempio: www.digicert.com

I problemi più comuni includono:

  • Problema: uso di un'autorità di certificazione non attendibile o di un certificato autofirmato

Correzione: utilizza un certificato SSL pubblico rilasciato dalla CA per il server di callback webhook.

CA non attendibile

  • Problema: il server non invia il certificato intermedio

Correzione: installare i certificati intermedi nel server di callback webhook.

Consulta https://www.digicert.com/kb/ssl-certificate-installation.htm per informazioni dettagliate.

Certificati intermedi mancanti

Verifica dei certificati client

Per configurare un SSL bidirezionale per un webhook, è necessario che l’amministratore carichi un file .p12 (o .pfx) che contiene la chiave privata. Il file viene archiviato in modo sicuro nell’account cliente e l’amministratore ha il pieno controllo per rimuoverlo in qualsiasi momento.

In un webhook bidirezionale, Acrobat Sign è il chiamante/cliente e ha bisogno della chiave privata per dimostrare che la chiamata è effettuata da Acrobat Sign per conto dell’account cliente.

  1. Verifica che l’SSL bidirezionale sia abilitato

    L’SSL bidirezionale deve essere abilitato sul server di callback webhook.

    Utilizzando qualsiasi browser web, connettiti all’URL di richiamata del webhook. Dovresti ricevere:

    400 Bad Request
    No required SSL certificate sent

    Ciò significa che il server si aspetta che il client invii certificati client (ovvero: SSL bidirezionale è abilitato per il server).

    Se il messaggio non è visualizzato, l’SSL bidirezionale non è abilitata.

    Nota:

    Puoi utilizzare Postman ed eseguire una richiesta di POST all'URL di callback del webhook. Dovresti ottenere un risultato simile.

  2. Verifica del certificato client localmente

    Le credenziali client possono essere un certificato autofirmato o un certificato rilasciato da CA. Tuttavia, deve essere minimamente conforme alle seguenti estensioni X.509 v3:

    Estensione X.509 v3

    Valore

    ExtendedKeyUsage

    clientAuth (OID: 1.3.6.1.5.5.7.3.2)

    KeyUsage

    digitalSignature

    Il certificato client deve essere un file PKCS12 con estensione .p12 o .pfx e deve includere sia il certificato client (in modo che il server possa verificare l'identità del client) e la chiave privata del client (in modo che il client possa firmare digitalmente i messaggi per il server da verificare durante la handshake SSL). 

    Utilizza la proprietà openssl per verificare il file p12 (pfx):

    openssl pkcs12 -info -in outfile.p12

    La passphrase per la chiave privata dovrebbe essere richiesta. L’output deve contenere entrambi i certificati nonché una chiave privata crittografata come:

    Bag Attributes
        localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
    subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
    issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
    -----BEGIN CERTIFICATE-----
    MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
    ...
    JAKQLQ==
    -----END CERTIFICATE-----
    Bag Attributes: <No Attributes>
    subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
    issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
    -----BEGIN CERTIFICATE-----
    MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
    ...
    -----END CERTIFICATE-----
    Bag Attributes
        localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
    Key Attributes: <No Attributes>
    -----BEGIN ENCRYPTED PRIVATE KEY-----
    MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
    ...
    FHE=
    -----END ENCRYPTED PRIVATE KEY-----

    I certificati devono includere come minimo il certificato di entità finale e i certificati intermedi. Idealmente, include anche il certificato CA radice.  

    Assicurati che il file .p12 o .pfx sia protetto da passphrase.

  3. Crea un certificato client autofirmato (facoltativo)

    I certificati client possono essere emessi da CA o autofirmati, a seconda delle esigenze.

    Per generare un certificato client autofirmato, utilizza il seguente comando openssl:

    openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

    Attenzione:

    Mantieni segreti i file risultanti poiché sono certificati CA autofirmati.

    Quindi, genera il file .p12 client:

    1. Genera una chiave privata per il client SSL:

      openssl genrsa -out client.key 2048

    2. Utilizza la chiave privata del client per generare una richiesta di certificato:

      openssl req -new -key client.key -out client.req

    3. Emetti il certificato client utilizzando la richiesta cert e la chiave/cert CA:

      openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer

    4. Converti il certificato client e la chiave privata in formato pkcs#12 per l'utilizzo da parte dei browser:

      openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12

    5. Rimuovi la chiave privata del client, il certificato del client e i file di richiesta del client poiché il pkcs12 contiene tutto ciò di cui hai bisogno.

      rm client.key client.cer client.req

  4. Verifica il certificato client sul server remoto

    • Utilizza Postman per caricare il file client PFX in Impostazioni > Certificati.
    • Seleziona Aggiungi certificato per aggiungere il certificato client.
    Impostazioni Postman

    • Configura l’intestazione HTTP per x-adobesign-clientid:
    Configurare l’intestazione

    Una volta configurata, invia una richiesta di POST all’URL di richiamata del webhook.

    Dovresti ricevere una risposta 200.

  5. Perché Acrobat Sign rifiuta il file PFX anche dopo averlo verificato con Postman?

    Se hai seguito la procedura di verifica dei file pfx descritta sopra e Acrobat Sign rifiuta ancora il file pfx, è probabile che il file sia stato generato da uno strumento Microsoft in grado di produrre un file PKCS12 non standard.

    In tal caso, utilizza i seguenti comandi openssl per estrarre i certificati e la chiave privata dal file pfx e quindi generare un file PKCS12 formattato correttamente:

    // Extract certificates and private key from pfx file
    openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
    openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts
    
    // Create new PKCS12 file
    openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx


Attivazione e disattivazione

L’accesso alla funzione Webhook è attivato per impostazione predefinita per gli account dei piani Enterprise.

Gli amministratori a livello di gruppo possono creare/controllare i webhook che operano solo all’interno del proprio gruppo.

L’accesso alla pagina Webhook si trova nella barra a sinistra del menu Amministratore: Account > Webhook


Attivare un webhook

Quando un webhook viene creato per la prima volta, viene creato in uno stato Attivo.

Nella pagina Webhook in Acrobat Sign, per impostazione predefinita vengono visualizzati i webhook attivi.

Per attivare un webhook inattivo:

  • Fai clic sull’icona Opzioni (tre linee orizzontali) a destra della riga di intestazione dei webhook e seleziona Mostra tutti i webhook

 

  • Fai un solo clic sul webhook intattivo per selezionarlo.
    • In questo modo vengono visualizzate appena sotto l’intestazione le opzioni per il webhook
  • Fai clic su Attiva

Il webhook attivo inizierà a inviare dati all’URL di destinazione non appena viene attivato l’evento successivo.


Disattivare un webhook

Per disattivare un webhook è sufficiente

  • Passare alla pagina Webhooks
  • Fare un solo clic sul webhook da disattivare
  • Selezionare Disattiva dalle voci di menu sotto la riga di intestazione
    • Una volta disattivato, il webhook mostra lo stato di Inattivo


Visualizzare o modificare un webhook

I webhook possono essere modificati e salvati in qualsiasi momento e, dopo aver salvato una nuova configurazione, la modifica ha effetto immediato.

Solo Eventi e Parametri di notifica possono essere modificati.

Per cambiare Nome, Ambito o URL è necessario creare un nuovo webhook.

Per modificare i parametri di un webhook:

  • Passare alla pagina Webhooks 
  • Fare un solo clic sul webhook da modificare
  • Fare clic sull’opzione Visualizza/Modifica sotto la riga di intestazione

 

  • Applica le modifiche necessarie e fai clic su Salva


Eliminare un webhook

Un webhook può essere eliminato in qualsiasi momento.

L’eliminazione di un webhook lo distrugge nel sistema, quindi non è possibile recuperare un webhook eliminato.

I webhook non devono essere disattivati per primi.

Per eliminare un webhook:

  • Passare a Webhook
  • Selezionare il webhook da eliminare facendo un solo clic su di esso
  • Fare clic sull’opzione Elimina sotto la riga di intestazione
  • Viene presentata una richiesta di conferma dell’eliminazione del webhook. fare clic su OK


Best practice

  • Resistente ai duplicati: se disponi di più app che condividono lo stesso URL del webhook e lo stesso utente è mappato su ciascuna app, lo stesso evento verrà inviato al webhook più volte (una volta per app). In alcuni casi, il webhook potrebbe ricevere eventi duplicati. L’applicazione webhook deve essere tollerante e deduplicata per ID evento.
  • Rispondi sempre rapidamente ai webhook: l’app ha solo dieci secondi per rispondere alle richieste di webhook. Per la richiesta di verifica, questo è raramente un problema, poiché l’app non deve eseguire alcun lavoro reale per rispondere. Per le richieste di notifica, tuttavia, l’app solitamente esegue un’operazione che richiede tempo per rispondere alla richiesta. 

Ad esempio, se devi elaborare e archiviare i documenti firmati. Per assicurarti di poter sempre rispondere entro dieci secondi, devi lavorare su un thread separato o in modo asincrono utilizzando una coda.

  • Gestire la concomitanza: quando un utente apporta una serie di modifiche in rapida successione, è probabile che l’app riceva più notifiche per lo stesso utente più o meno nello stesso momento. Se non presti attenzione a come gestisci la concomitanza, l’app potrebbe elaborare le stesse modifiche per lo stesso utente più di una volta. 
  • Per sfruttare i webhook di Acrobat Sign, è necessario comprendere chiaramente l’utilizzo delle informazioni. Assicurati di porre domande quali: 

1. Quali dati desideri restituire nel payload? 

2. Chi accederà a queste informazioni? 

3. Quali decisioni o rapporti verranno generati?

  • Recommendations per la ricezione di un documento firmato: quando si determina come ricevere un PDF firmato da Acrobat Sign nel sistema di gestione dei documenti, è necessario considerare diversi fattori. 

Anche se è perfettamente accettabile selezionare solo il Documento accordo firmato durante la creazione di un webhook, è possibile valutare l’utilizzo dell’API di Acrobat Sign per recuperare i documenti quando viene ricevuto un evento di attivazione (ad esempio, lo stato dell’accordo Completo).


Aspetti da considerare...

Limitazione della dimensione JSON

La dimensione del payload JSON è limitata a 10 MB.

Nel caso in cui un evento generi un payload più grande, verrà attivato un webhook, ma gli attributi dei parametri condizionali, se presenti nella richiesta, vengono rimossi per ridurre le dimensioni del payload. 

Se questo si verifica, la risposta presenta “ConditionalParametersTrimmed” per informare il cliente che le informazioni  conditionalParameters  sono state rimosse.

conditionalParametersTrimmed” è un oggetto array contenente informazioni sulle chiavi che sono state tagliate.

Il troncamento verrà eseguito nel seguente ordine:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

I documenti firmati verranno troncati per primi, seguiti da informazioni sul partecipante, informazioni sul documento e, infine, informazioni dettagliate.

Questo può accadere, ad esempio, in un evento di completamento dell’accordo che include un documento firmato (codificato in base 64) o in un accordo con più campi modulo.


Notifiche webhook

I webhook di Acrobat Sign forniscono notifiche applicabili a tutti i partecipanti di un accordo se è configurato un webhook per tale utente, il suo gruppo o il suo account.

Gli eventi dell’accordo vengono elaborati in modo che, se è presente un webhook configurato per il partecipante applicabile all’evento, viene inviata una notifica all’URL del webhook. In altre parole, i webhook vengono attivati per gli eventi in tutti gli accordi applicabili, anche quelli esterni al gruppo o all’account in cui è configurato il webhook.

Le notifiche vengono inviate solo per gli eventi in cui è coinvolto il partecipante. Ad esempio, la proprietà Mittente di un accordo riceve quasi tutte le notifiche, mentre i Destinatari riceveranno notifiche solo dall’inizio del loro coinvolgimento nell’accordo e solo per gli eventi in cui sono coinvolti.

Le notifiche webhook seguono il modello di autenticazione e visibilità corrente di Acrobat Sign stesso, il che significa che gli utenti avranno accesso all’accordo solo una volta iniziata la loro partecipazione a un accordo.

Il Mittente invia un accordo per la firma a tre firmatari.

  • C’è un livello account WebhookX configurato per l’account Mittenti.
  • Signer1 è un membro dello stesso account del mittente ma in un gruppo diverso, per il quale è stato configurato un WehbhookY.
  • Signer2 è un membro di un account diverso, e per l’account di Signer2 è stato configurato un WebhookZ a livello di account.
  • Signer3 è un membro dello stesso account del mittente.

Il Mittente invia un accordo: WebhookX viene attivato dagli eventi “Accordo creato” e “Accordo inviato”, mentre WebhookY viene attivato dall’evento “Accordo inviato”.

Signer1 firma: WebhookX viene attivato dagli eventi “Accordo partecipante completato” e “Accordo inviato”; WebhookY viene attivato dall’evento “Accordo partecipante completato”; e WebhookZ viene attivato dall’evento “Accordo inviato”.

Signer2 firma: WebhookX viene attivato dagli eventi “Accordo partecipante completato” e “Accordo inviato”, mentre WebhookZ invia una notifica per “Accordo partecipante completato”.

Signer3 firma: WebhookX viene attivato dagli eventi “Accordo partecipante completato” e “Accordo flusso di lavoro completato”; WebhookY viene attivato dall’evento “Accordo flusso di lavoro completato”; e WebhookZ viene attivato dall’evento “Accordo flusso di lavoro completato”.


Riprova quando il servizio di ascolto non è attivo

Se l’URL di destinazione per il webhook è inattivo per qualsiasi motivo, Acrobat Sign mette in coda il codice JSON e tenta di inviarlo di nuovo in un ciclo progressivo di 72 ore.

Gli eventi non consegnati vengono mantenuti in una coda di tentativi e nelle successive 72 ore verrà fatto il possibile per inviare le notifiche nell’ordine in cui si sono verificate.

La strategia di ripetere i tentativi di consegna delle notifiche prevede il raddoppiamento del tempo tra tentativi successivi, a partire da un intervallo di 1 minuto che aumenta fino a 12 ore, per un totale di 15 tentativi nell’arco di 72 ore.

Se il ricevitore del webhook non risponde entro 72 ore e negli ultimi sette giorni non sono state inviate notifiche, il webhook verrà disabilitato. Non verrà inviata alcuna notifica a questo URL finché il webhook non sarà nuovamente attivato.

Tutte le notifiche tra il momento in cui il webhook viene disattivato e successivamente riattivato verranno perse.

Logo Adobe

Accedi al tuo account