Webhookは、従業員がフォームを送信すると、送信データを外部システムに自動的に送信します。そのため、誰かが手作業でデータをエクスポート、インポート、または再入力する必要はありません。技術チームが構築したインテグレーションサービスと組み合わせることで、Webhookは別のシステムでワークフローをトリガーできます。たとえば、インシデント報告、HRリクエスト、経費精算フォームのデータを、チケット管理、HR、または経費精算システムに直接送信できます。
すべてのWebhookには認証シークレットが含まれているため、受信システムはリクエストがStaffbase環境から送信されたことを確認できます。Webhook、メール通知、受信者への質問のどれを選択するかについては、送信データのルーティング方法を選択するを参照してください。
Webhookの仕組み
1回の送信につき、1つのWebhookイベントがトリガーされます。Staffbaseは、JSON本文を含むPOSTリクエストとして、イベントをHTTPSエンドポイントに送信します。ペイロードには、回答データと、ユーザープロフィールのフィールドから収集するよう選択したメタデータが含まれます。これには、システムフィールドと組織固有のカスタムフィールドが含まれます。
配信に失敗した場合、Staffbaseはエンドポイントへのリクエストを再試行します。
フォームにWebhookを追加する方法については、フォーム設定を使用するを参照してください。追加した後、Webhookの横にある3つのドットを選択すると、テスト、編集、または削除ができます。
- 配信: テストを送信を選択して、テストイベントを送信します。配信IDとレスポンスステータスコードが表示されます。テスト配信には「テスト」と表示されます。
- 編集: Webhook URLを変更したり、シークレットをコピーまたは再生成したりします。シークレットを再生成した後は、以前の配信が完了するまで、以前のシークレットとそのキーIDを保持してください。これらのイベントの再試行では、引き続き古いシークレットが使用されるためです。
- 削除: Webhookを削除します。確認を求める警告が表示されます。
Webhookペイロードについて
JSONペイロードには、次の情報が含まれます。
-
フォームインストールID: フォームの一意の識別子です。Studioで確認するには、フォームのアクションメニューを開き、リンクをコピーを選択します。IDはURLの末尾の部分です。
https://<your-environment>/content/staffbase.forms/<form-installation-ID> - フォームタイトル: フォームの名前です。タイトルは一意の識別子ではありません。
- 送信ID: 送信の一意の識別子です。同じ従業員が複数回送信した場合でも、送信ごとに異なる値が割り当てられます。
- 回答者データ: 回答とともに収集されたユーザープロフィール情報です。デフォルトでは、名と姓が含まれます。フォーム設定の「回答者データ」で、追加のプロフィールフィールドを収集できます。フォームで匿名回答を使用している場合、ユーザー情報は含まれません。
-
回答: 回答された質問への回答です。各回答には
questionIdとquestionLabelが含まれます。質問キーを設定した場合、回答にはquestionKeyも含まれます。
質問キーの設定
質問キーを使用すると、ペイロードを読み取りやすくし、受信システムでマッピングしやすくできます。質問キーは小文字で始まり、小文字、数字、アンダースコアのみを含み、64文字以内である必要があります。削除した質問のキーを含め、キーはフォーム内で一意である必要があります。
- エディターでフォームを開きます。
- 質問を選択し、鉛筆アイコンを選択して質問設定を開きます。
- 質問キーを入力します。
- 変更を反映するには、フォームを公開または更新します。
すでにキューに追加されている配信では、元のキーが引き続き使用されます。
Webhookのセキュリティ保護
Webhookを受信するには、URLをWebに公開する必要があります。Staffbaseは各ペイロードにWebhookシークレットを使用して署名するため、システムは処理前にリクエストが正当なものであることを検証できます。リクエストを検証するには、次の手順を実行します。
- リクエストヘッダー
X-Staffbase-Webhook-Timestamp、X-Staffbase-Webhook-Delivery-Id、X-Staffbase-Webhook-Key-Id、X-Staffbase-Webhook-Signatureを読み取ります。 - シークレットをbase64urlからバイト列にデコードします。
-
次のUTF-8プレフィックスに、変更されていない正確なリクエスト本文のバイト列を続けたものに対して、HMAC-SHA256を計算します。
v1.<timestamp>.<deliveryId>.<keyId>.
- 結果をパディングなしのbase64urlとしてエンコードし、
v1=を先頭に付けます。その値を、定時間比較を使用して署名ヘッダーと比較します。
Staffbaseでは、受信側に次の追加の保護対策を推奨しています。
- タイムスタンプの有効性を確認します。たとえば、5分間の許容範囲を設定します。タイムスタンプはUnix秒です。
- 再送された配信IDを拒否します。
- 再試行をべき等に処理します。すべての再試行には新しい配信IDが割り当てられますが、
X-Staffbase-Webhook-Idは同じです。すでにそのイベントを処理している場合は、再度処理せずに2xxレスポンスを返します。
コメント
0件のコメント
サインインしてコメントを残してください。