Webhooksを使用すると、Sign.Plus内のエンベロープのステータスに関するリアルタイム更新を受け取ることができます。 この記事では、Sign.Plus統合のためのWebhookの設定と取り扱いのプロセスをご案内します。
ステップ 1: Webhookを作成
リアルタイムアップデートの受信を開始するには、まずSign.PlusでWebhookを作成する必要があります。 方法は次のとおりです。
- Webhook通知を受信するターゲットURLを決定します。 これは、受信した POST リクエストを処理するように設定されているサーバーのエンドポイントである必要があります。
- 追跡するイベントを選択します。 Sign.Plus は以下の webhook イベントを提供しています。
-
envelope_completed- 封筒が完成した場合 -
envelope_expired- 封筒が期限切れの場合 -
envelope_declined- 封筒が拒否された場合 -
envelope_voided- 封筒が無効の場合
-
- Sign.Plus API を使用して Web フックを作成します。 追跡するターゲット URL とイベントを指定する必要があります。
Sign.Plus API を使用して Webhook を作成する方法の詳細については、 Webhook エンドポイントの作成ドキュメント を参照してください。
ステップ2：Webフック表記を処理
Webhookを設定すると、Sign.Plusはトラッキングイベントが発生するたびに、指定したURLにPOSTリクエストを送信します。 これらの通知の処理について知っておくべきことは次のとおりです。
-
Request Method: すべての webhook 通知は HTTP
POSTリクエストとして送信されます。 -
ペイロード構造: Webhookペイロードは2つの主なセクションを含むJSONオブジェクトです:
-
hook: Webhook自体に関するメタデータが含まれています。 -
データ: イベントをトリガーしたエンベロープに関する情報が含まれます。
-
-
Payload Examples: Here are examples of payloads for different events:
// ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
} -
通知の取り扱い: サーバが Web フックの通知を受け取った場合:
- ペイロードを確認して、有効な webhook 通知であることを確認します。
- ペイロードから関連情報を抽出します。
- イベント タイプに基づいて必要なアクションを実行します (たとえば、データベースの更新、ユーザーへの通知、他のプロセスのトリガーなど)。
- Webhookの受領確認のため、
200 OKの返答を送信してください。
ベストプラクティス
- セキュリティ: Webhookエンドポイントが安全であることを確認します。 Webhook URL に認証を実装することを検討してください。
- Idempotency: Webフックハンドラを設計してください。 これは、同じWebhookが複数回受信されても同じ結果を生成することを意味します。
- エラーハンドリング: Webhook処理ロジックに堅牢なエラーハンドリングを実装します。
このガイドに従うことで、Webhookを効果的に設定して処理することができます。 アプリケーションがサイン内のエンベロープステータスに関するリアルタイム更新を受信できるようにします。 ロース!