Webhook実行時の挙動

対応者：クラウドサイン運営事務局

書類が、Webhookの追加時に設定した「通知する条件」の状態になると、指定された URL に対してHTTP リクエストを行います。

HTTP リクエスト

このセクションでは指定された URL に対してクラウドサインが行う HTTP リクエストについて説明します。

前提

クラウドサインの Webhook によるリクエストは以下の前提です。

プロトコル
- HTTPS
- HTTP（非推奨です。今後廃止される可能性があります）

プロトコル

HTTPS

HTTP（非推奨です。今後廃止される可能性があります）

SSL/TLSのバージョン
- TLS1.3
- TLS1.2
暗号スイート
- TLS_RSA_WITH_AES_128_CBC_SHA（非推奨です。今後廃止される可能性があります）
- TLS_RSA_WITH_AES_256_CBC_SHA（非推奨です。今後廃止される可能性があります）
- TLS_RSA_WITH_AES_128_GCM_SHA256（非推奨です。今後廃止される可能性があります）
- TLS_RSA_WITH_AES_256_GCM_SHA384（非推奨です。今後廃止される可能性があります）
- TLS_AES_128_GCM_SHA256
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

SSL/TLSのバージョン

TLS1.3

TLS1.2

暗号スイート

TLS_RSA_WITH_AES_128_CBC_SHA（非推奨です。今後廃止される可能性があります）

TLS_RSA_WITH_AES_256_CBC_SHA（非推奨です。今後廃止される可能性があります）

TLS_RSA_WITH_AES_128_GCM_SHA256（非推奨です。今後廃止される可能性があります）

TLS_RSA_WITH_AES_256_GCM_SHA384（非推奨です。今後廃止される可能性があります）

TLS_AES_128_GCM_SHA256

TLS_AES_256_GCM_SHA384

TLS_CHACHA20_POLY1305_SHA256

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

送信元

クラウドサインの Webhook は環境ごとに以下のIPアドレスから HTTP リクエストを行います。

本番環境の場合

sandbox環境の場合

リクエストメソッド

クラウドサインの Webhook は POST メソッドで送信します。

リクエストヘッダ

クラウドサインの Webhook は以下のヘッダを送信します。

Content-Type: application/json
User-Agent: CloudSignWebHook
Body: {JSON}

Content-Type: application/json

User-Agent: CloudSignWebHook

Body: {JSON}

リクエストボディ

クラウドサインの Webhook は HTTP リクエストボディとしてJSON形式のテキストデータを送信します。

JSON の内容はたとえば以下のようになります。なお、見やすくするように改行を入れていますが、実際には1行で、プロパティ名と値の間には空白は入りません。

JSONの各プロパティの詳細

2024年12月時点での JSON のプロパティは以下です。

プロパティは予告なく追加される可能性がありますのでご了承ください。

documentID:

documentID は書類を一意に識別する ID です。書類の詳細を取得するには、書類取得 API GET /documents/{documentID} をご利用ください。

documentID は書類を一意に識別する ID です。書類の詳細を取得するには、書類取得 API GET /documents/{documentID} をご利用ください。

status:

status は書類の状態を示す1桁の整数値です。以下の3種のいずれかの値をとります。
- 1: 先方確認中
- 2: 締結完了
- 3: 取り消し・却下

status は書類の状態を示す1桁の整数値です。以下の3種のいずれかの値をとります。

1: 先方確認中

2: 締結完了

3: 取り消し・却下

userID:

UserID は、クラウドサイン内でユーザーを一意に識別するための ID です。ここでは書類の送信者の ID が記されます。

UserID は、クラウドサイン内でユーザーを一意に識別するための ID です。ここでは書類の送信者の ID が記されます。

email:

email は、書類の送信者のメールアドレスです。

email は、書類の送信者のメールアドレスです。

text:

text は、Webhookメッセージの本体となる部分です。書類に関する以下のような情報が記されます。
- Webhookメッセージの種類
  - COMPLETED: 書類の締結完了時
  - CANCELED: 書類の取り消し・却下時
  - BOUNCED: 確認依頼メール、転送メール、締結完了メールの不達時
    
    ※どの種類のメールが不達になったかは、上記statusプロパティの値によってご確認いただけます。
    
    statusが「1」：確認依頼メール or 転送メール
    
    statusが「2」：締結完了メール
- 書類のタイトル
- 送信者の名前
- クラウドサイン上の書類確認用 URL

text は、Webhookメッセージの本体となる部分です。書類に関する以下のような情報が記されます。

Webhookメッセージの種類

COMPLETED: 書類の締結完了時
CANCELED: 書類の取り消し・却下時
BOUNCED: 確認依頼メール、転送メール、締結完了メールの不達時
- ※どの種類のメールが不達になったかは、上記statusプロパティの値によってご確認いただけます。
  - statusが「1」：確認依頼メール or 転送メール
  - statusが「2」：締結完了メール

Webhookメッセージの種類

COMPLETED: 書類の締結完了時

CANCELED: 書類の取り消し・却下時

BOUNCED: 確認依頼メール、転送メール、締結完了メールの不達時

※どの種類のメールが不達になったかは、上記statusプロパティの値によってご確認いただけます。
- statusが「1」：確認依頼メール or 転送メール
- statusが「2」：締結完了メール

BOUNCED: 確認依頼メール、転送メール、締結完了メールの不達時

※どの種類のメールが不達になったかは、上記statusプロパティの値によってご確認いただけます。

statusが「1」：確認依頼メール or 転送メール
statusが「2」：締結完了メール

※どの種類のメールが不達になったかは、上記statusプロパティの値によってご確認いただけます。

statusが「1」：確認依頼メール or 転送メール

statusが「2」：締結完了メール

書類のタイトル

送信者の名前

クラウドサイン上の書類確認用 URL

HTTP レスポンス

このセクションでは指定された URL からクラウドサインへの HTTP レスポンスについて説明します。

ステータスコード

クラウドサインの Webhook では 2024年12月時点で HTTP ステータスコードを参照していません。

今後ステータスコードを参照する実装に切り替える可能性があるため、受信できた場合には 200-299 のステータスコードを返すようにしてください。

レスポンスヘッダ

クラウドサインの Webhook は HTTP レスポンスヘッダを参照しません。

レスポンスボディ

クラウドサインの Webhook は HTTP レスポンスボディを参照しません。

エラー時の挙動

クラウドサインの Webhook では指定された URL にアクセスした際にエラーが発生した場合 Webhook の再送を行いません。

Webhookの実行に失敗する場合

Webhookの実行が失敗する場合はいくつかの原因が考えられます。下記をご確認ください。

Webhook URLの設定
- Webhook URLが設定されていることや設定したWebhook URLに誤りがないかをご確認ください。
- Webhook URLの設定方法は「Webhook 機能」をご確認ください。
サーバーの証明書
- Webhookを受信するサーバーに証明書(中間CA証明書等)が正しく導入されているかをご確認ください。

Webhook URLの設定

Webhook URLが設定されていることや設定したWebhook URLに誤りがないかをご確認ください。

Webhook URLの設定方法は「Webhook 機能」をご確認ください。

サーバーの証明書

Webhookを受信するサーバーに証明書(中間CA証明書等)が正しく導入されているかをご確認ください。

Webhook 機能

Webhook 機能

Webhook実行時の挙動 | クラウドサイン ヘルプセンター