Handboek Annuleren

 Overzicht van Acrobat Sign-webhooks

 

Handboek voor Adobe Acrobat Sign

Nieuwe functies

Aan de slag

Beheerder

Overeenkomsten verzenden, ondertekenen en beheren

Geavanceerde voorzieningen en workflows voor overeenkomsten

Integreren met andere producten

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.
Opmerking:

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.

Navigeren naar het tabblad Webhooks

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
(gebeurtenis)

Maximumaantal
gelijktijdige
gebeurtenissen

Beschrijving

Creatie van een webhook

10

Er worden per account maximaal 10 gelijktijdige aanvragen voor het maken van een webhook toegestaan.
Aanvragen die deze limiet overschrijden, resulteren in de antwoordcode 429 TOO_MANY_REQUESTS.

Webhook-/callbackmelding

30

Er zijn maximaal 30 gelijktijdige webhook- en callbackmeldingen per account toegestaan.
Voor meldingen die deze limiet overschrijden, wordt een nieuwe poging gedaan volgens een exponentiele back-off totdat ze worden afgeleverd.

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

Webhook-meldingen

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.

Krijg sneller en gemakkelijker hulp

Nieuwe gebruiker?