Webhookを使用すると、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を使用してWebhookを作成します。ターゲットURLと追跡したいイベントを指定する必要があります。
Sign.Plus APIを使用してWebhookを作成する方法の詳細については、Create a webhookエンドポイントのドキュメントを参照してください。
ステップ2: Webhook通知を処理する
Webhookを設定すると、追跡対象のイベントが発生するたびに、Sign.Plusから指定したURLへPOSTリクエストが送信されます。これらの通知を処理する際に知っておくべきことは次のとおりです。
-
リクエストメソッド: すべてのWebhook通知はHTTPの
POSTリクエストとして送信されます。
-
ペイロードの構造: Webhookのペイロードは、以下の2つの主要な部分を含むJSONオブジェクトです。
-
hook: Webhook自体に関するメタデータを含みます。
-
data: イベントを発生させたエンベロープに関する情報を含みます。
-
-
ペイロードの例: 異なるイベントに対するペイロードの例は次のとおりです。
// 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"
}
} -
通知の処理: サーバーがWebhook通知を受信した場合:
- ペイロードを検証し、有効なWebhook通知であることを確認します。
- ペイロードから関連情報を抽出します。
- イベントの種類に応じて、必要な処理を実行します（例: データベースの更新、ユーザーへの通知、他のプロセスのトリガーなど）。
-
200 OKレスポンスを送信して、Webhookの受信を確認します。
Sign.PlusのWebhookは、以下の許可されたIPアドレスからのみ送信されます:
34.65.253.117
34.65.146.131
ベストプラクティス
- セキュリティ: Webhookエンドポイントが安全であることを確認してください。Webhook URLの認証機能の実装も検討してください。
- 冪等性（idempotency）: Webhookハンドラーは冪等になるように設計してください。つまり、同じWebhookが複数回受信された場合でも、同じ結果が得られるようにする必要があります。
- エラー処理: Webhook処理ロジックに堅牢なエラー処理を実装してください。
このガイドに従うことで、Webhookを効果的に設定・処理できるようになり、アプリケーションがSign.Plus内のエンベロープのステータスに関するリアルタイムの更新を受け取れるようになります。