Esempio di codice Javascript per recuperare l’ID client, convalidarlo e quindi restituirlo nell’intestazione della risposta
Novità
Introduzione
- Guida introduttiva per gli amministratori
- Guida introduttiva per gli utenti
- Libreria tutorial video
- Domande frequenti
Amministrazione
- Panoramica su Admin Console
-
Gestione degli utenti
- Aggiunta di utenti
- Creare utenti con funzioni specifiche
- Verificare la presenza di utenti con errori di provisioning
- Modificare il nome/l’indirizzo e-mail
- Modificare l’iscrizione a un gruppo di un utente
- Promuovere un utente a un ruolo di amministratore
- Tipi di identità utente e SSO
- Cambiare l’identità utente
- Autenticare gli utenti con Microsoft Azure
- Autenticare gli utenti con la Federazione Google
- Profili di prodotti
- Esperienza di accesso
-
Impostazioni account/gruppo
- Panoramica delle impostazioni
-
Impostazioni generali
- Nuova esperienza del destinatario
- Flussi di lavoro per firma autonoma
- Invia in modalità collettiva
- Moduli web
- Flussi di lavoro Power Automate
- Documenti libreria
- Raccogliere i dati modulo con gli accordi
- Visibilità limitata dei documenti
- Allegare una copia PDF dell’accordo firmato
- Includere un collegamento nell’e-mail
- Includere un’immagine nell’e-mail
- Denominazione dei file allegati alle e-mail
- Allegare report di audit ai documenti
- Unire più documenti in uno solo
- Scarica documenti singoli
- Caricare un documento firmato
- Impostare un fuso orario predefinito
- Utenti in più gruppi
- Autorizzazioni amministratore gruppo
- Sostituzione del destinatario
- Report di audit
- Piè di pagina transazione
- Cliente nel settore sanitario
- Configurazione dell’account
-
Preferenze firma
- Firme formattate correttamente
- Personalizzare le Condizioni d'uso e l’Informativa cliente
- Guida per i destinatari ai campi del modulo
- Riavvia il flusso di lavoro dell’accordo
- Rifiuto di firmare
- Consentire ai firmatari di stampare e apporre una firma manuale
- Chiedere ai firmatari di creare la firma con un dispositivo mobile
- Richiedere indirizzo IP dei destinatari
- Firme digitali
- Sigilli elettronici
- Identità digitale
-
Impostazioni report
- Impostazioni di protezione
-
Impostazioni di invio
- Richiedere il nome del destinatario all’invio
- Bloccare i valori dei nomi per gli utenti noti
- Ruoli destinatario consentiti
- Consentire e-Witnesses
- Gruppi di destinatari
- Cc
- Accesso dei destinatari agli accordi
- Appiattisci i campi
- Modificare gli accordi
- Messaggi privati
- Tipi di firma consentiti
- Promemoria
- Invia notifica di invio accordo tramite
- Opzioni di identificazione firmatari
- Protezione contenuti
- Ordine di firma
- Liquid Mode
- Impostazioni Bio-Pharma
- Impostazioni autenticazione
- Integrazione per pagamenti
- Impostazioni SAML
- Governance dei dati
- Impostazioni marca temporale
- Archivio esterno
- Lingue account
- Impostazioni e-mail
- Migrazione da echosign.com ad adobesign.com
- Configurare le opzioni per i destinatari
-
Linee guida per i requisiti normativi
- Accessibilità
- HIPAA
- GDPR
- 21 CFR parte 11 ed EudraLex Annex 11
- Clientela del settore sanitario
- Supporto IVES
- Accordi di “archiviazione”
- Considerazioni UE/Regno Unito
- Richiedere il proprio dominio
- Collegamenti Segnala abuso
Inviare, firmare e gestire gli accordi
-
Opzioni destinatari
- Annullare un promemoria tramite e-mail
-
Opzioni disponibili nella pagina di firma elettronica
- Panoramica della pagina di firma elettronica
- Aprire per leggere l’accordo senza campi
- Rifiutare di firmare un accordo
- Delegare autorizzazioni di firma
- Scaricare un file PDF dell’accordo
- Visualizzare la cronologia dell’accordo
- Visualizzare i messaggi dell’accordo
- Convertire una firma elettronica in una manuale
- Convertire una firma da manuale a elettronica
- Aggiungere i campi modulo
- Cancellare i dati dai campi modulo
- Navigazione e ingrandimento della pagina Firma elettronica
- Cambiare la lingua utilizzata nelle informazioni e negli strumenti per gli accordi
- Rivedere le note legali
- Regolare le preferenze dei cookie Acrobat Sign
-
Inviare gli accordi
- Panoramica sulla pagina Invia
- Inviare un accordo solo a se stessi
- Inviare un accordo agli altri
- Firme manuali
- Ordine di firma del destinatario
-
Invia in modalità collettiva
- Panoramica della funzione Invia in modalità collettiva
- Invio in modalità collettiva: configurare un modello principale
- Invio in modalità collettiva: configurare un file CSV
- Annullare una transazione per l’invio in modalità collettiva
- Aggiungere promemoria all’invio in modalità collettiva
- Reporting per Invia in modalità collettiva
-
Authoring dei campi nei documenti
-
Ambiente di authoring in-app
- Rilevamento automatico dei campi
- Trascinare i campi utilizzando l’ambiente di authoring
- Assegnare i campi modulo ai destinatari
- Ruolo di precompilazione
- Applicare campi con un modello per campi riutilizzabili
- Trasferire i campi in un nuovo modello libreria
- Ambiente di authoring aggiornato durante l’invio degli accordi
- Creare moduli e tag di testo
- Creare moduli con Acrobat (AcroForms)
- Campi
- Domande frequenti sull’authoring
-
Ambiente di authoring in-app
- Firmare gli accordi
-
Gestire gli accordi
- Panoramica della pagina Gestisci
- Delegare gli accordi
- Sostituire i destinatari
- Limitare la visibilità del documento
- Annullare un accordo
- Creare nuovi promemoria
- Revisione dei promemoria
- Annullare un promemoria
- Accedere ai flussi Power Automate
-
Altre azioni...
- Come funziona la ricerca
- Visualizzare un accordo
- Creare un modello da un accordo
- Nascondere/Mostrare gli accordi nella visualizzazione
- Caricare un accordo firmato
- Modificare i file e i campi di un accordo inviato
- Modificare il metodo di autenticazione di un destinatario
- Aggiungere o modificare una data di scadenza
- Aggiungere una nota a un accordo
- Condividere un singolo accordo
- Annullare la condivisione di un accordo
- Scaricare un singolo accordo
- Scaricare i singoli file di un accordo
- Scaricare il report di audit di un accordo
- Scaricare il contenuto dei campi di un accordo
- Report di audit
- Rapporti ed esportazioni di dati
Funzionalità e flussi di lavoro avanzati per gli accordi
- Moduli web
-
Modelli riutilizzabili
- Moduli per la Pubblica amministrazione degli Stati Uniti nella libreria Acrobat Sign
- Creare un modello libreria
- Modificare il nome di un modello libreria
- Modificare il tipo di un modello libreria
- Modificare il livello di autorizzazione di un modello libreria
- Copiare, modificare e salvare un modello condiviso
- Scaricare i dati dei campi aggregati per un modello libreria
- Trasferire la proprietà dei moduli web e dei modelli libreria
-
Flussi di lavoro Power Automate
- Panoramica dell’integrazione Power Automate e diritti inclusi
- Abilitare l’integrazione di Power Automate
- Azioni nel contesto sulla pagina Gestisci
- Tracciare l’utilizzo di Power Automate
- Creare un nuovo flusso (esempi)
- Trigger utilizzati per i flussi
- Importazione di flussi dall’esterno di Acrobat Sign
- Gestire i flussi
- Modificare i flussi
- Condividere i flussi
- Disabilitare o abilitare i flussi
- Eliminare i flussi
-
Modelli utili
- Solo per l’amministratore
- Archiviazione dell’accordo
- Archiviazione del modulo web dell’accordo
- Estrazione dati dall’accordo
- Notifiche per l’accordo
- Generazione degli accordi
- Flussi di lavoro di invio personalizzati
- Condividere utenti e accordi
Integrazione con altri prodotti
- Panoramica delle integrazioni di Acrobat Sign
- Acrobat Sign per Salesforce
- Acrobat Sign per Microsoft
- Altre integrazioni
- Integrazioni gestite dai partner
- Come ottenere una chiave di integrazione
Acrobat Sign per sviluppatori
Supporto e risoluzione dei problemi
Panoramica
Un webhook è una richiesta HTTPS definita dall’utente che viene attivata quando si verifica un evento di abbonamento nel sito di origine (Adobe Acrobat Sign in questo caso).
In pratica, un webhook non è altro che un servizio REST che accetta dati o flussi di dati.
I webhook sono pensati per la comunicazione service-to-service in un Modello PUSH.
Quando viene attivato un evento di abbonamento, Acrobat Sign crea un POST HTTPS con un corpo JSON e lo invia all’URL specificato.
Prima di configurare i webhook, assicurati che la tua rete accetti gli intervalli IP necessari per la funzionalità.
I webhook offrono numerosi vantaggi rispetto al precedente metodo di richiamata, tra cui:
- Gli amministratori possono abilitare i propri webhook senza dover coinvolgere il supporto di Acrobat Sign per indicare l’URL di richiamata
- I webhook sono migliori in termini di “freschezza” dei dati, efficienza della comunicazione e sicurezza. 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) in cui le richiamate devono essere univoche.
- I webhook consentono di restituire la selezione dei dati, in cui le richiamate 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.
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:
Prerequisiti
È necessario consentire intervalli IP per webhook tramite la sicurezza di rete affinché il servizio funzioni.
Il servizio URL di richiamata precedente in REST v5 utilizza gli stessi intervalli IP del servizio webhook.
Gli amministratori possono accedere ad Adobe Admin Console per aggiungere gli utenti. Una volta effettuato l’accesso, accedi al menu dell’amministratore e scorri verso il basso fino a Webhook.
Come utilizzare questa funzionalità
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 (Widget) o Invio in modalità collettiva (MegaSign). La risorsa Modello libreria (Documento libreria) può anche essere configurata tramite l’API.
L’ambito del webhook può includere l’intero account o i singoli gruppi tramite l’interfaccia di amministrazione. L'API consente una maggiore granularità attraverso la selezione degli ambiti UTENTE o RISORSA.
Il tipo di dati che vengono inviati all’URL è configurabile e può includere informazioni sull’accordo, sul partecipante, sul documento e così via.
Una volta configurato e salvato il webhook, Acrobat Sign trasmetterà un nuovo oggetto JSON all’URL definito ogni volta che l’evento di abbonamento viene attivato. 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 correttamente 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, effettua prima 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 relativo URL deve rispondere a questa richiesta di verifica con un codice di risposta 2XX E, inoltre, DEVE 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 xAdobeSignClientId. 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 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 del 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 chiave xAdobeSignClientId e con il valore dello stesso ID client. In caso contrario, riproveremo a recapitare la notifica all’URL del webhook fino a quando non saranno esauriti i tentativi.
Attivazione e disattivazione
L’accesso alla funzione Webhook è attivato per impostazione predefinita per gli account di livello 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.
Limitazione della frequenza basata sulla concomitanza
Gli eventi di creazione e notifica di webhook (e richiamata) sono limitati nel numero di notifiche concomitanti che vengono attivamente consegnate al cliente dal sistema Acrobat Sign. Questo limite si applica all’account e include tutti i gruppi presenti al suo interno.
Questo tipo di limitazione della frequenza impedisce che un account mal progettato consumi una quantità sproporzionata di risorse del server, con conseguente impatto negativo su tutti gli altri clienti in quell’ambiente server.
Il numero di eventi concomitanti per account è stato calcolato per garantire che gli account con webhook funzionanti ricevano le notifiche nel più breve tempo possibile e che raramente si verifichino situazioni in cui le notifiche subiscano ritardi a causa di troppe richieste. Le soglie attuali sono:
Azione |
Eventi |
Descrizione |
Creazione di webhook |
10 |
Sono consentite al massimo 10 richieste di creazione simultanee di webhook per account. |
Notifica webhook/richiamata |
30 |
Sono consentite al massimo 30 notifiche simultanee di webhook e richiamata per account. |
Best practice
- Per limitare il numero di richieste HTTPS al server, puoi abbonarti a specifici eventi: più specifici sono i webhook, meno volume sarà necessario esaminare.
- 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 cinque 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. Si consiglia di lavorare su un thread separato o in modo asincrono utilizzando una coda per garantire una risposta entro cinque secondi
- 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:
- Quali dati desideri restituire nel payload?
- Chi accederà a queste informazioni?
- Quali decisioni o rapporti verranno generati?
- Raccomandazioni 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 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.
I webhook di Acrobat Sign forniscono notifiche al mittente dell’accordo e a qualsiasi webhook configurato all’interno del gruppo da cui è stato inviato l’accordo. I webhook con ambito account ricevono tutti gli eventi.
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.