Voorbeeld van Javascript-code voor het ophalen, valideren en retourneren van de client-ID naar de koptekst van het antwoord
Handboek voor Adobe Acrobat Sign
Nieuwe functies
Aan de slag
- Snelstartgids voor beheerders
- Handleiding om snel aan de slag te gaan voor gebruikers
- Bibliotheek voor videotutorial
- Veelgestelde vragen
Beheerder
- Overzicht Admin Console
-
User Management
- Gebruikers toevoegen
- Op functies gerichte gebruikers maken
- Controleren op gebruikers met provisioningfouten
- Naam/e-mailadres wijzigen
- Groepslidmaatschap van een gebruiker bewerken
- Een gebruiker tot een beheerdersrol bevorderen
- Typen gebruikersidentiteiten en SSO
- Gebruikersidentiteit wisselen
- Gebruikers verifiëren met MS Azure
- Gebruikers verifiëren met Google Federation
- Productprofielen
- Aanmeldingservaring
-
Account-/groepsinstellingen
- Overzicht van instellingen
-
Algemene instellingen
- Nieuwe ervaring voor ontvangers
- Workflows voor zelfondertekening
- In bulk verzenden
- Webformulieren
- Power Automate-workflows
- Bibliotheekdocumenten
- Formuliergegevens bij overeenkomsten verzamelen
- Beperkte documentzichtbaarheid
- Een PDF-kopie van de ondertekende overeenkomst bijvoegen
- Een koppeling opnemen in de e-mail
- Een afbeelding opnemen in de e-mail
- Bestanden die bij een e-mail worden gevoegd, krijgen de naam
- Controlerapport bij documenten bijvoegen
- Meerdere documenten samenvoegen tot één document
- Afzonderlijke documenten downloaden
- Een ondertekend document uploaden
- De standaard tijdzone instellen
- Gebruikers in meerdere groepen (UMG)
- Machtigingen voor groepsbeheerder
- Ontvanger vervangen
- Controlerapport
- Voettekst van transactie
- Klant in de gezondheidszorg
- Account instellen
-
Voorkeuren handtekening
- Goed ingedeelde handtekeningen
- Aangepaste gebruiksvoorwaarden en openbaarmakingsbeleid
- Ontvangers door formuliervelden navigeren
- Overeenkomstworkflow opnieuw starten
- Weigeren te ondertekenen
- Ondertekenaars toestaan een schriftelijke handtekening af te drukken en te plaatsen
- Vereisen dat ondertekenaars een mobiel apparaat gebruiken om hun handtekening te maken
- Verzoeken om IP-adres van ondertekenaars
- Digitale handtekeningen
- Elektronische zegels
- Digitale identiteit
-
Rapportinstellingen
- Beveiligingsinstellingen
-
Verzendinstellingen
- Ontvangersnaam bij verzenden vereisen
- Naamwaarden voor bekende gebruikers vergrendelen
- Toegestane ontvangersrollen
- Elektronische getuigen toestaan
- Ontvangersgroepen
- CC's
- Toegang tot overeenkomst voor de ontvanger
- Velden afvlakken
- Overeenkomsten wijzigen
- Privéberichten
- Toegestane handtekeningtypes
- Herinneringen
- Overeenkomstbericht verzenden via
- Opties voor indentificatie van ondertekenaar
- Inhoudsbeveiliging
- Handtekeningvolgorde
- Liquid Mode
- Bio-Pharma-instellingen
- Notariële instellingen
- Betalingsintegratie
- SAML-instellingen
- Voorschriften voor gegevens
- Instellingen tijdstempel
- Extern archiveren
- Accounttalen
- E-mailinstellingen
- Migreren van echosign.com naar adobesign.com
- Configuratieopties voor ontvangers
-
Begeleiding voor regelgevingsvereisten
- Toegankelijkheid
- HIPAA
- AVG
- 21 CFR deel 11 en EudraLex bijlage 11
- Klanten in de gezondheidszorg
- IVES-ondersteuning
- Overeenkomsten archiveren
- Overwegingen voor EU/VK
- Uw domein claimen
- Koppelingen voor het melden van misbruik
Overeenkomsten verzenden, ondertekenen en beheren
-
Opties voor ontvangers
- Een e-mailherinnering annuleren
-
Opties op de pagina voor elektronisch ondertekenen
- Overzicht van de pagina voor elektronisch ondertekenen
- Openen om de overeenkomst zonder velden te lezen
- Weigeren om een overeenkomst te ondertekenen
- Ondertekeningsbevoegdheid delegeren
- Een PDF van de overeenkomst downloaden
- Geschiedenis van de overeenkomst weergeven
- Berichten over de overeenkomst weergeven
- Een elektronische handtekening naar een geschreven handtekening converteren
- Een geschreven handtekening naar een elektronische handtekening converteren
- Door formuliervelden navigeren
- De gegevens uit de formuliervelden wissen
- Vergroting en navigatie van de pagina voor elektronisch ondertekenen
- De taal wijzigen die wordt gebruikt in de tools en informatie van de overeenkomst
- Juridische kennisgevingen controleren
- Cookievoorkeuren voor Acrobat Sign aanpassen
- Overeenkomsten verzenden
-
Velden in documenten opnemen
-
In-app authoringomgeving
- Automatische velddetectie
- Velden slepen en neerzetten met de authoringomgeving
- Formuliervelden toewijzen aan ontvangers
- De rol Vooraf invullen
- Velden aanbrengen met een herbruikbare veldsjabloon
- Overdracht van velden naar een nieuwe bibliotheeksjabloon
- Bijgewerkte authoringomgeving bij het verzenden van overeenkomsten
- Formulieren met tekstlabels maken
- Formulieren maken met Acrobat (AcroForms)
- Velden
- Veelgestelde vragen over ontwerpen
-
In-app authoringomgeving
- Overeenkomsten ondertekenen
-
Overeenkomsten beheren
- Overzicht pagina Beheren
- Overeenkomsten delegeren
- Ontvangers vervangen
- Documentzichtbaarheid beperken
- Een overeenkomst annuleren
- Nieuwe herinneringen maken
- Herinneringen voor beoordeling
- Een herinnering annuleren
- Toegang verkrijgen tot Power Automate-flows
-
Meer handelingen...
- De werking van de zoekfunctie
- Een overeenkomst weergeven
- Een sjabloon maken op basis van een overeenkomst
- Overeenkomsten verbergen/zichtbaar maken
- Een ondertekend document uploaden
- Bestanden en velden van een verzonden overeenkomst wijzigen
- De verificatiemethode van een ontvanger bewerken
- Een vervaldatum toevoegen of wijzigen
- Een opmerking toevoegen aan een overeenkomst
- Een individuele overeenkomst delen
- Delen van een overeenkomst ongedaan maken
- Een individuele overeenkomst downloaden
- De afzonderlijke bestanden van een overeenkomst downloaden
- Het controlerapport van een overeenkomst downloaden
- De veldinhoud van een overeenkomst downloaden
- Controlerapport
- Rapportage en gegevensexports
Geavanceerde voorzieningen en workflows voor overeenkomsten
- Webformulieren
-
Herbruikbare sjablonen
- US Government-formulieren in de Acrobat Sign-bibliotheek
- Een bibliotheeksjabloon maken
- De naam van een bibliotheeksjabloon wijzigen
- Het type van een bibliotheeksjabloon wijzigen
- Het machtigingsniveau van een bibliotheeksjabloon wijzigen
- Een gedeelde sjabloon kopiëren, bewerken en opslaan
- De verzamelde veldgegevens voor een bibliotheeksjabloon downloaden
- Eigendom van webformulieren en bibliotheeksjablonen overdragen
-
Power Automate-workflows
- Overzicht van de Power Automate-integratie en opgenomen rechten
- De Power Automate-integratie inschakelen
- Contextuele acties op de pagina Beheren
- Gebruik van Power Automate bijhouden
- Een nieuwe flow maken (voorbeelden)
- Triggers die worden gebruikt voor flows
- Flows van buiten Acrobat Sign importeren
- Flows beheren
- Flows bewerken
- Flows delen
- Flows in- of uitschakelen
- Flows verwijderen
-
Nuttige sjablonen
- Alleen beheerder
- Archivering van overeenkomst
- Archivering van webformulierovereenkomst
- Data-extractie van de overeenkomst
- Overeenkomstmeldingen
- Overeenkomst genereren
- Workflows op maat verzenden
- Gebruikers en overeenkomsten delen
Integreren met andere producten
- Acrobat Sign voor Salesforce
- Acrobat Sign voor Microsoft
- Overige integraties
- Door partners beheerde integraties
- Een integratiesleutel verkrijgen
Acrobat Sign Developer
Ondersteuning en probleemoplossing
Overzicht
Een webhook is een door de gebruiker gedefinieerd HTTPS-verzoek dat wordt geactiveerd wanneer een subscribed gebeurtenis plaatsvindt op de bronsite (in dit geval Adobe Acrobat Sign).
Een webhook is dus gewoon een REST-service die gegevens of een gegevensstroom accepteert.
Webhooks zijn bedoeld voor service-tot-service communicatie in een PUSH-model.
Wanneer zich een subscribed gebeurtenis voordoet, construeert Acrobat Sign een HTTPS-POST met een JSON-hoofdtekst en levert deze aan de opgegeven URL.
Voordat u webhooks configureert, moet u ervoor zorgen dat uw netwerk de IP-bereiken accepteert die nodig zijn voor functionaliteit.
Webhooks bieden meerdere voordelen ten opzichte van de vorige callbackmethode, bijvoorbeeld:
- Beheerders kunnen hun eigen webhooks inschakelen zonder Acrobat Sign-ondersteuning voor het weergeven van de callback-URL
- Webhooks zijn beter betreffende "versheid" van gegevens, de efficiëntie van communicatie en beveiliging. Geen polling vereist
- Met webhooks wordt het gebruik van verschillende bereiken eenvoudiger (Account/Groep/Gebruiker/Bron).
- Webhooks bieden een modernere API-oplossing, waardoor moderne applicaties eenvoudiger kunnen worden geconfigureerd
- U kunt meerdere webhooks per bereik configureren (Account/Groep/Gebruiker/Bron), terwijl callbacks uniek moesten zijn
- Bij webhooks kunt u specifiek aangeven welke gegevens worden geretourneerd. Bij callbacks is dit een "alles of niets"-optie
- De metagegevens die zijn opgenomen in een webhook, kunnen worden geconfigureerd (standaard of gedetailleerd)
- Webhooks kunnen veel eenvoudiger worden gemaakt, bewerkt of, indien nodig, uitgeschakeld, omdat de gebruikersinterface volledig binnen de controle van de beheerder valt.
Dit document is voornamelijk gericht op de webhooks-UI in de Acrobat Sign-internettoepassing (voorheen Adobe Sign).
Ontwikkelaars die meer willen weten over API kunnen hier de gewenste informatie vinden:
Vereisten
U moet de IP-bereiken voor webhooks toestaan via uw netwerkbeveiliging om de service te laten werken.
De verouderde callback-URL-service in REST v5 gebruikt dezelfde IP-bereiken als de webhookservice.
Beheerders kunnen zich aanmelden bij de Adobe Admin Console om gebruikers toevoegen. Als u bent aangemeld, gaat u naar het beheerdersmenu en scrolt u omlaag naar Webhooks.
Gebruik
Beheerders moeten eerst een webhookservice hebben waarmee binnenkomende pushmeldingen van Acrobat Sign worden geaccepteerd. Er zijn in dit opzicht veel opties en zolang de service POST- en GET-verzoeken kan accepteren, zal de webhook succesvol zijn.
Zodra de service is ingesteld, kan een Acrobat Sign-beheerder een nieuwe webhook maken via de Webhook-interface in het menu Account van de Acrobat Sign-site.
Beheerders kunnen de webhook zodanig configureren dat deze wordt geactiveerd voor Overeenkomst-, Webformulier (Widget)- of 'In bulk verzenden' (MegaSign)-gebeurtenissen. Bibliotheeksjabloonbron (Bibliotheekdocument) kan ook worden geconfigureerd via de API.
Het bereik van de webhook kan een heel account of afzonderlijke groepen omvatten. Dit gebeurt via de beheerinterface. De API maakt meer granulariteit mogelijk door de selectie van de bereiken GEBRUIKER of BRON.
Het type gegevens dat naar de URL wordt gepusht, is configureerbaar en kan zaken omvatten zoals informatie over de overeenkomst, de deelnemer, het document, enzovoort.
Zodra de webhook is geconfigureerd en opgeslagen, pusht Acrobat Sign een nieuw JSON-object naar de gedefinieerde URL telkens wanneer de subscribed gebeurtenis wordt geactiveerd. U hoeft de webhook niet voortdurend te bewerken of te controleren, tenzij u de criteria voor triggergebeurtenissen of de JSON-payload wilt wijzigen.
Verificatie van de bedoeling van de webhook -URL
Voordat een webhook succesvol wordt geregistreerd, verifieert Acrobat Sign of de webhook-URL die in het registratieverzoek is opgegeven, bedoeld is om meldingen te ontvangen of niet. Daarom dient Acrobat Sign, wanneer het een nieuw webhook-registratieverzoek ontvangt, eerst een verificatieverzoek in bij de webhook-URL. Dit verificatieverzoek is een HTTPS GET-aanvraag die naar de webhook-URL is verzonden. Deze aanvraag heeft een aangepaste HTTP-header X-AdobeSign-ClientId. De waarde in deze header is ingesteld op de client-ID (applicatie-ID) van de API-applicatie die de aanvraag voor het maken/registreren van de webhook indient. Voordat een webhook succesvol kan worden geregistreerd, moet de webhook-URL aan dit verificatieverzoek voldoen met een 2XX-antwoordcode EN daarnaast MOET dezelfde client-ID-waarde worden teruggestuurd op een van de volgende twee manieren:
- In een X-AdobeSign-ClientId-responsheader. Dit is dezelfde koptekst die is doorgegeven in de oorspronkelijke aanvraag en die in de respons moet worden 'teruggekaatst'.
- In de JSON-hoofdtekst van de respons met de sleutel xAdobeSignClientId en de waarde die gelijk is aan de client-ID die in de koptekst van de aanvraag is verzonden.
De webhook wordt alleen geregistreerd bij een succesvolle respons (2XX-responscode) en validatie van de client-ID in de kop- of hoofdtekst van de respons.Het doel van dit verificatieverzoek is om aan te tonen dat uw webhook-URL ook daadwerkelijk meldingen wil ontvangen op de desbetreffende URL. Als u per ongeluk een verkeerde URL hebt ingevoerd, reageert de URL niet correct op de verificatieaanvraag en stuurt Acrobat Sign geen meldingen meer naar die URL. Daarnaast kan de webhook-URL ook valideren dat de URL alleen meldingen ontvangt via de webhooks die zijn geregistreerd bij een specifieke applicatie. Hiervoor moet u de client-ID van de toepassing valideren die wordt doorgegeven in de X-AdobeSign-ClientId-header. Als deze client-ID niet wordt herkend door de webhook-URL, moet deze NIET reageren met de antwoordcode voor succes. Acrobat Sign zal er in dat geval voor zorgen dat de URL niet als webhook wordt geregistreerd.
Verificatie van de webhook-URL-aanroep wordt in de volgende gevallen uitgevoerd:
- Bij registratie van de webhook: als de verificatie van de webhook-URL-aanroep mislukt, wordt de webhook niet gemaakt.
- Bij het bijwerken van de webhook van NIET-ACTIEF naar ACTIEF: als de verificatie van de webhook-URL-aanroep mislukt, wordt de status van de webhook niet gewijzigd naar ACTIEF.
Reageren op een webhookmelding
Acrobat Sign voert een impliciete verificatie van de intentie uit in elk webhookmeldingsverzoek dat naar de webhook-URL wordt verzonden. Zo bevat elk webhookmeldings-HTTPS-verzoek ook de aangepaste HTTP header genaamd X-AdobeSign-ClientId. De waarde van deze header is de client-ID (Application ID) van de toepassing waarmee de webhook is gemaakt De levering van de webhookmelding geldt alleen als succesvol wanneer een succesreactie (2XX antwoordcode) wordt geretourneerd en de client-ID wordt verzonden in de HTTP-header (X-AdobeSign-ClientId) of in een JSON-antwoordtekst met sleutel als xAdobeSignClientId en waarde als dezelfde client-ID, anders proberen we de melding opnieuw naar de webhook-URL te sturen totdat de nieuwe pogingen zijn opgebruikt.
In- of uitschakelen
Toegang tot de webhookfunctie is standaard ingeschakeld voor accounts op ondernemingslaag.
Beheerders op groepniveau kunnen webhooks maken/controleren die alleen binnen de groep functioneren.
Als u de pagina Webhooks wilt openen, gaat u naar de linkerkant van het menu Beheer.
Limiet voor snelheid op basis van gelijktijdigheid
Het maken van webhooks, callbacks en meldingsgebeurtenissen zijn beperkt in het aantal gelijktijdige meldingen dat actief vanuit het Acrobat Sign-systeem aan de klant wordt afgeleverd. Deze limiet geldt voor het account, inclusief alle groepen binnen het account.
Dit type limiet voor snelheid voorkomt dat één slecht ontworpen account een onevenredige hoeveelheid serverresources verbruikt, waardoor alle andere klanten in die serveromgeving negatief worden beïnvloed.
Het aantal gelijktijdige gebeurtenissen per account is berekend om ervoor te zorgen dat accounts met goed beheerde webhooks meldingen in de kortst mogelijke tijd ontvangen en zelden te maken krijgen met een situatie waarin meldingen worden vertraagd door te veel aanvragen. De huidige drempels zijn:
Actie |
Maximumaantal |
Beschrijving |
Creatie van een webhook |
10 |
Er worden per account maximaal 10 gelijktijdige aanvragen voor het maken van een webhook toegestaan. |
Webhook-/callbackmelding |
30 |
Er zijn maximaal 30 gelijktijdige webhook- en callbackmeldingen per account toegestaan. |
Best practices
- Meld u aan voor specifieke, noodzakelijke gebeurtenissen om het aantal HTTPS-verzoeken aan de server te beperken - Hoe specifieker u uw webhooks kunt maken, hoe minder volume u hoeft door te nemen.
- Bestand tegen duplicatie - Als u één en dezelfde webhook-URL deelt met meerdere apps, en als dezelfde gebruiker is toegewezen aan elke app, wordt dezelfde gebeurtenis meerdere keren naar uw webhook verzonden (één keer per app). In sommige gevallen kan uw webhook dubbele gebeurtenissen ontvangen. Uw webhooktoepassing moet hiermee kunnen omgaan en dedupliceren op gebeurtenis-ID.
- Altijd snel antwoorden op webhooks - Uw app heeft slechts tien seconden om te reageren op webhookverzoeken. Voor het verificatieverzoek is dit slechts zelden een probleem, aangezien uw app hoeft geen echt werk hoeft te doen om te reageren. Bij meldingsverzoeken doet de app als reactie op het verzoek meestal iets dat tijd kost. Het wordt aanbevolen om met een wachtrij aan een aparte thread of asynchroon te werken om ervoor te zorgen dat u binnen vijf seconden kunt reageren
- Gelijktijdigheid beheren - Wanneer een gebruiker snel achter elkaar een aantal veranderingen aanbrengt, ontvangt uw app waarschijnlijk meerdere meldingen voor dezelfde gebruiker op ongeveer hetzelfde tijdstip. Als u niet goed oplet bij het beheer van gelijktijdigheid, is het mogelijk dat de app dezelfde wijzigingen voor dezelfde gebruiker meermalen aanbrengt. Om te profiteren van Acrobat Sign-webhooks moet u een duidelijk begrip hebben van het gebruik van de informatie. Stel uzelf de volgende vragen:
- Welke gegevens wilt u retourneren in de payload?
- Wie heeft toegang tot deze informatie?
- Welke beslissing of rapportage wordt hierdoor gegenereerd?
- Aanbevelingen voor het ontvangen van een ondertekend document - Er zijn verschillende factoren waarmee u rekening moet houden bij het bepalen hoe u een ondertekende PDF van Acrobat Sign in uw documentbeheersysteem ontvangt.
Hoewel het volkomen acceptabel is om gewoon de optie Overeenkomst van ondertekend document te selecteren tijdens het maken van een webhook, kunt u overwegen de Acrobat Sign-API te gebruiken om de documenten op te halen wanneer een activerende gebeurtenis (zoals de overeenkomststatus Voltooid) is ontvangen.
Dingen om rekening mee te houden...
Beperking van JSON-grootte
De grootte van de JSON-lading is beperkt tot 10 MB.
Als een gebeurtenis een grotere payload genereert, wordt een webhook geactiveerd, maar de attributen van voorwaardelijke parameters, als die aanwezig zijn in het verzoek, worden verwijderd om de payload te verkleinen.
Wanneer dit gebeurt, wordt 'ConditionalParametersTrimmed' in het antwoord geretourneerd om de client te informeren dat de informatie over de conditionalParameters is verwijderd.
“conditionalParametersTrimmed” is een array-object met informatie over de sleutels die zijn afgekapt.
De afkapping vindt plaats in de onderstaande volgorde:
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
De ondertekende documenten worden eerst worden afgekapt, gevolgd door deelnemerinformatie op, documentgegevens en de uiteindelijke gedetailleerde informatie.
Dit kan bijvoorbeeld op een gebeurtenis ook gebeuren als het agreement ondertekend document (versleutelde grondtal 64) of voor een agreement met meerdere formuliervelden bevat
Acrobat Sign-webhooks leveren meldingen aan de afzender van de overeenkomst, en aan elke webhook die is geconfigureerd binnen de groep van waaruit de overeenkomst is verzonden. Webhooks met accountbereik ontvangen alle gebeurtenissen.
Probeer het opnieuw wanneer de listening-service niet beschikbaar is
Als de doel-URL voor de webhook om welke reden dan ook niet beschikbaar is, zal Acrobat Sign de JSON in de wachtrij plaatsen en de push opnieuw proberen in een progressieve cyclus van 72 uur.
De niet-afgeleverde gebeurtenissen worden bewaard in een wachtrij voor opnieuw proberen en er wordt de komende 72 uur alles aan gedaan om de meldingen af te leveren in de volgorde waarin ze zijn opgetreden.
De strategie voor het opnieuw proberen van de levering van meldingen is een verdubbeling van de tijd tussen pogingen, beginnend met een interval van 1 minuut oplopend tot elke 12 uur, wat resulteert in 15 nieuwe pogingen in een tijdsbestek van 72 uur.
Als de webhookontvanger niet binnen 72 uur reageert en er in de afgelopen zeven dagen geen succesvolle leveringen van meldingen zijn geweest, wordt de webhook uitgeschakeld. Geen meldingen worden naar dit URL opnieuw verzonden tot webhook wordt geactiveerd.
Alle meldingen webhook tussen het moment is uitgeschakeld en het later opnieuw ingeschakeld, zullen verloren gaan.