Hoe webhooks configureren om op de hoogte gebracht te worden van nieuwe PDF-formulierinzendingen

Benjamin André-Micolon

Een krachtige manier om de inzendingen naar uw applicatie te sturen of SimplePDF te verbinden met andere diensten zoals Zapier of Activepieces is het gebruik van webhooks.

Webhooks?

Webhooks maken het mogelijk om applicaties met elkaar te verbinden door gegevens in realtime van de ene applicatie naar de andere(n) te sturen wanneer een bepaalde gebeurtenis plaatsvindt.

In SimplePDF wordt elke keer dat een PDF wordt ingediend via uw bedrijfsportaal, hetzij via formulierlinks of integratie in uw website, een gebeurtenis verstuurd met onder andere de documentnaam, een link naar de ingevulde PDF en een link naar de gestructureerde formuliergegevens.

De gestructureerde formuliergegevens zijn het deel waar de meeste integraties om draaien: in plaats van de ingevulde PDF te ontleden, ontvangt u elk antwoord als JSON, klaar om op te slaan, door te sturen of door te geven aan een ander systeem. Zie De gestructureerde formuliergegevens extraheren hieronder.

Vanaf daar zijn de mogelijkheden eindeloos en kunt u uw fantasie de vrije loop laten.

U zou bijvoorbeeld die informatie in een Google Sheet kunnen opslaan of het integreren met Zapier of Activepieces en nog meer mogelijkheden ontsluiten!

Webhooks configureren in SimplePDF

Webhooks configureren is beschikbaar met het BASIC-abonnement

• Log in op uw account
• Navigeer naar de accountinstellingen

• Klik op Configuratie bijwerken
• Voer de webhook-URL in van de dienst of applicatie waarnaar u gebeurtenissen wilt sturen

• Optioneel: geef de headers op die als onderdeel van de webhook moeten worden meegestuurd

Dat is het! Er wordt een gebeurtenis verstuurd bij elke nieuwe inzending

Webhook-gebeurtenissen

Hieronder vindt u de gebeurtenissen die door SimplePDF naar de door u geconfigureerde webhook worden verstuurd.

type: "submission.created",
data: {
  document: {
    id: "b7615a68-9e1f-4eac-bd20-5e80632a4d9e",
    name: "your_document.pdf",
  },
  submission: {
    id: "80146d5b-a068-490f-8eb9-fe393ba11396",
    submitted_at: "2023-06-04T11:54:58.995Z",
    url: "short_lived_15min_url",
    field_data_url: "short_lived_15min_url",
  },
  context: {
    environment: "production",
    customer_id: "123"
  }
}

De gestructureerde formuliergegevens extraheren

field_data_url is een kortstondige link naar de formuliergegevens van de inzending als JSON, zodat u de ingevulde PDF nooit hoeft te ontleden om de antwoorden te lezen.

Het legt elk veld vast, of het nu een veld is dat in de PDF is ingebouwd (een native formulierveld, ook wel AcroField genoemd) of een veld dat uw ontvanger heeft ingevuld en dat u bovenop het document in SimplePDF hebt toegevoegd. Beide verschijnen in dezelfde lijst, elk met hun id, hun name en de ingediende value:

{
  "fields": [
    { "id": "first_name__widget_1", "name": "First name", "value": "Jane" },
    { "id": "agreed_to_terms__widget_1", "name": "Agreed to terms", "value": "checked" },
    { "id": "f_a1b2c3", "name": "Reviewer note", "value": "A note added on top of the PDF" }
  ]
}

Elke value is platte tekst (een handtekening of afbeelding wordt als ingesloten afbeelding meegestuurd). Omdat elke invoer zowel de id als de name bevat, kunt u elk antwoord aan zijn veld koppelen en het rechtstreeks in een spreadsheet, een database of een downstream-formulier zoals een FHIR-questionnaire-response invoeren. Precies dezelfde JSON kan terug naar SimplePDF worden gestuurd om een ander document voor te vullen, zodat een inzending de volledige cyclus netjes doorloopt.

De velden op een document zijn stabiel en u bepaalt hoe elk veld wordt genoemd: configureer uw velden één keer (hernoem ze, markeer ze als verplicht, stel standaardwaarden in) en elke toekomstige inzending komt binnen met dezelfde id en name. Daarmee wordt het koppelen van webhookgegevens aan uw eigen systeem een eenmalige instelling die daarna ongewijzigd voor elke inzending werkt. (name is null voor een veld dat u bovenop hebt toegevoegd maar nooit hebt benoemd.)

field_data_url verloopt na 15 minuten, net als url. Als u het later nodig hebt, haal dan een nieuwe op via de API met GET /documents/{document_id}/submissions/{submission_id}. Het is null voor inzendingen die zijn vastgelegd voordat gestructureerde formuliergegevens beschikbaar waren.

Over de context

Wanneer u SimplePDF integreert in uw website, wilt u mogelijk aanvullende informatie koppelen aan inzendingen.

U wilt bijvoorbeeld:

• Weten of de inzending is gestart vanuit een ontwikkel-environment versus een production-omgeving.
• Aanvullende gegevens sturen over wie het formulier heeft ingediend (zoals een ingelogde gebruiker) wat het voor u makkelijker maakt om de inzending te verwerken.

Leer hoe u een context opgeeft in de documentatie van SimplePDF embed

Playground

We houden van voorbeelden bij SimplePDF, dus wat dacht u van een praktijkvoorbeeld van hoe webhooks eruit zien?

1. Wijzig de context hieronder (klik om de inhoud te bewerken)

{"environment":"production","customer_id":"123"}

2. Dien dit formulier in

3. De webhook die door SimplePDF is verstuurd verschijnt hier

Als u vragen heeft, neem dan gerust contact op via support@simplepdf.com