Webhooks für Benachrichtigungen bei neuen PDF-Formulareinreichungen konfigurieren

Benjamin André-Micolon

Eine leistungsstarke Möglichkeit, Einreichungen an Ihre Anwendung zu senden oder SimplePDF mit anderen Diensten wie Zapier oder Activepieces zu verbinden, sind Webhooks.

Webhooks?

Webhooks ermöglichen es, Anwendungen miteinander zu verbinden, indem sie Daten in Echtzeit von einer Anwendung an die andere(n) senden, sobald ein bestimmtes Ereignis eintritt.

In SimplePDF wird jedes Mal, wenn ein PDF eingereicht wird - über Ihr Unternehmensportal, entweder über Formular-Links oder eingebettet in Ihre Website - ein Event gesendet, das unter anderem den Dokumentnamen, einen Link zum ausgefüllten PDF und einen Link zu den strukturierten Formulardaten enthält.

Die strukturierten Formulardaten sind der Teil, der für die meisten Integrationen am wichtigsten ist: Statt das ausgefüllte PDF zu analysieren, erhalten Sie jede Antwort als JSON, bereit zum Speichern, Weiterleiten oder Übergeben an ein anderes System. Siehe Die strukturierten Formulardaten extrahieren weiter unten.

Von dort an sind die Möglichkeiten grenzenlos und Sie können Ihrer Fantasie freien Lauf lassen.

Sie könnten zum Beispiel diese Informationen in einem Google Sheet speichern oder mit Zapier oder Activepieces integrieren und noch mehr Möglichkeiten erschließen!

Webhooks in SimplePDF konfigurieren

Die Konfiguration von Webhooks ist mit dem BASIC-Tarif verfügbar

• Melden Sie sich in Ihrem Konto an
• Navigieren Sie zur Kontoeinstellungen-Ansicht

• Klicken Sie auf Update configuration
• Geben Sie die Webhook-URL des Dienstes oder der Anwendung ein, an die Sie Events senden möchten

• Optional: Geben Sie die Header an, die als Teil des Webhooks gesendet werden sollen

Das war's! Ein Event wird bei jeder neuen Einreichung gesendet

Webhook-Events

Nachfolgend finden Sie die Events, die SimplePDF an den von Ihnen konfigurierten Webhook sendet.

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"
  }
}

Die strukturierten Formulardaten extrahieren

field_data_url ist ein kurzlebiger Link zu den Formulardaten der Einreichung als JSON, sodass Sie das ausgefüllte PDF nie analysieren müssen, um die Antworten auszulesen.

Er erfasst jedes Feld, ob es sich um ein im PDF eingebautes Feld handelt (ein natives Formularfeld, auch AcroField genannt) oder um ein Feld, das Ihr Empfänger ausgefüllt hat und das Sie in SimplePDF zusätzlich auf das Dokument gelegt haben. Beide erscheinen in derselben Liste, jeweils mit ihrer id, ihrem name und dem übermittelten 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" }
  ]
}

Jeder value ist Klartext (eine Unterschrift oder ein Bild wird als eingebettetes Bild übertragen). Da jeder Eintrag sowohl die id als auch den name trägt, können Sie jede Antwort ihrem Feld zuordnen und sie direkt in eine Tabelle, eine Datenbank oder ein nachgelagertes Formular wie eine FHIR-Questionnaire-Response einspeisen. Genau dasselbe JSON kann an SimplePDF zurückgesendet werden, um ein weiteres Dokument vorauszufüllen, sodass eine Einreichung sauber den vollständigen Kreislauf durchläuft.

Die Felder eines Dokuments sind stabil, und Sie bestimmen, wie jedes benannt wird: konfigurieren Sie Ihre Felder einmal (benennen Sie sie um, markieren Sie sie als erforderlich, legen Sie Standardwerte fest), und jede künftige Einreichung trifft mit derselben id und demselben name ein. Das macht die Zuordnung der Webhook-Daten zu Ihrem eigenen System zu einer einmaligen Einrichtung, die danach für jede Einreichung unverändert läuft. (name ist null für ein Feld, das Sie zusätzlich aufgelegt, aber nie benannt haben.)

field_data_url läuft nach 15 Minuten ab, genau wie url. Wenn Sie ihn später benötigen, rufen Sie einen frischen über die API mit GET /documents/{document_id}/submissions/{submission_id} ab. Er ist null für Einreichungen, die vor der Verfügbarkeit strukturierter Formulardaten erfasst wurden.

Über den Kontext

Wenn Sie SimplePDF in Ihre Website integrieren, möchten Sie möglicherweise zusätzliche Informationen an Einreichungen knüpfen.

Zum Beispiel möchten Sie vielleicht:

• Wissen, ob die Einreichung aus einer Entwicklungsumgebung (environment) oder einer Produktionsumgebung (production) stammt.
• Zusätzliche Details darüber senden, wer das Formular eingereicht hat (z. B. ein angemeldeter Nutzer), um die Verarbeitung der Einreichung zu erleichtern.

Erfahren Sie, wie Sie einen context angeben, in der Dokumentation von SimplePDF Embed

Playground

Bei SimplePDF mögen wir Beispiele - wie wäre es also mit einem Praxisbeispiel, wie Webhooks aussehen?

1. Passen Sie den Kontext unten an (klicken Sie, um den Inhalt zu bearbeiten)

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

2. Reichen Sie dieses Formular ein

3. Der von SimplePDF gesendete Webhook erscheint hier

Wenn Sie Fragen haben, wenden Sie sich gerne an support@simplepdf.com