PDFフォーム送信の通知用にWebhookを設定する方法

Benjamin André-Micolon

提出されたPDFフォームがsubmission.created Webhookをトリガーし、ドキュメント名、入力済みPDFへのリンク、JSON形式の構造化フォームデータを伝送して、Google Sheets、Slack、Zapier、Activepieces、そしてお客様のアプリケーションへ展開する様子

送信データをアプリケーションに送ったり、SimplePDFをZapierやActivepiecesなどのサービスと接続する強力な方法として、Webhookがあります。

Webhookとは？

Webhookは、特定のイベントが発生するたびに、あるアプリケーションから別のアプリケーションにリアルタイムでデータを送信することで、アプリケーション同士を接続する仕組みです。

SimplePDFでは、PDFが送信されるたびに、フォームリンクまたはウェブサイトへの埋め込みを通じて、ドキュメント名、入力済みPDFへのリンク、そして構造化されたフォームデータへのリンクなどの情報を含むイベントが送信されます。

構造化されたフォームデータは、ほとんどの連携で最も重視される部分です。入力済みPDFを解析する代わりに、各回答をJSONとして受け取り、保存、振り分け、または別のシステムへの受け渡しにそのまま利用できます。詳しくは下記の構造化されたフォームデータを抽出するをご覧ください。

そこからは可能性は無限大です。

たとえば、その情報をGoogleスプレッドシートに保存したり、ZapierやActivepiecesと連携してさらに多くの可能性を引き出すことができます！

SimplePDFでWebhookを設定する

Webhookの設定はBASICプランでご利用いただけます。

アカウントにログインします
アカウント設定画面に移動します

アカウント画面でWebhookを設定

Update configurationをクリックします
イベントを送信したいサービスやアプリケーションのWebhook URLを入力します

Webhook設定：設定詳細

任意：Webhookの一部として送信するヘッダーを指定します

新しい送信があるたびにイベントが送信されるようになりました！

Webhookイベント

SimplePDFから設定したWebhookに送信されるイベントは以下の通りです。

新しい送信

ペイロード

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

構造化されたフォームデータを抽出する

field_data_urlは、送信のフォームデータをJSON形式で取得できる短時間有効なリンクです。これにより、回答を読み取るために入力済みPDFを解析する必要が一切なくなります。

PDFに組み込まれたフィールド（AcroFieldとも呼ばれるネイティブのフォームフィールド）であっても、受信者が入力した、SimplePDFでドキュメント上に追加したフィールドであっても、すべてのフィールドを取得します。どちらも同じ一覧に表示され、それぞれがid、name、および送信されたvalueを保持します。

フォームデータ

field_data_urlから取得

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

各valueはプレーンテキストです（署名や画像はインライン画像として含まれます）。各エントリがidとnameの両方を保持しているため、各回答をそのフィールドに対応付けて、スプレッドシート、データベース、またはFHIRのクエスチョネアレスポンスのような下流のフォームに直接取り込むことができます。まったく同じJSONをSimplePDFに送り返して別のドキュメントを事前入力することもできるため、送信はきれいに往復します。

ドキュメント上のフィールドは安定しており、それぞれの名前の付け方はご自身で管理できます。フィールドを一度設定する（名前を変更したり、必須に設定したり、デフォルト値を設定したり）だけで、今後のすべての送信が同じidとnameで届きます。これにより、Webhookデータをご自身のシステムに対応付ける作業は一度きりの設定となり、その後はすべての送信に対して変更なしで機能します。（ドキュメント上に追加したものの名前を付けなかったフィールドの場合、nameはnullになります。）

field_data_urlはurlと同様に15分後に期限切れになります。後で必要になった場合は、APIからGET /documents/{document_id}/submissions/{submission_id}で新しいものを取得してください。構造化されたフォームデータが利用可能になる前に記録された送信については、nullになります。

コンテキストについて

SimplePDFをウェブサイトに統合する際、送信に追加情報を関連付けたい場合があります。

たとえば、以下のようなことが可能です：

送信が開発environmentからなのか、productionからなのかを把握する。
フォームを送信した_人物_に関する追加情報（ログインユーザーなど）を送信し、送信の処理を容易にする。

contextの指定方法については、SimplePDF embedのドキュメントをご覧ください。

プレイグラウンド

SimplePDFでは実例を大切にしています。Webhookが実際にどのように動作するか見てみましょう。

以下のコンテキストを編集してください（クリックして内容を編集できます）

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

このフォームを送信してください
SimplePDFから送信されたWebhookがこちらに表示されます

ご質問がございましたら、お気軽にsupport@simplepdf.comまでご連絡ください。