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

HTTP リクエスト

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

前提

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

プロトコル
- 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

送信元

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

本番環境の場合

52.68.17.229/32 または 52.198.144.82/32 または 3.112.114.42/32

sandbox環境の場合

52.197.119.179/32

リクエストメソッド

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

リクエストヘッダ

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

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

リクエストボディ

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

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

{
"documentID": "{documentID}",
"status": 2,
"userID": "{userID}",
"email": "user@example.com",
"text": "COMPLETED : 業務委託契約 sent by Jane Doe\n<https://www.cloudisign.jp/document/{documentID}/summary>"
}

JSONの各プロパティの詳細

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

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

documentID:

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

status:

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

userID:

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

email:

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

text:

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

HTTP レスポンス

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

ステータスコード

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

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

レスポンスヘッダ

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

レスポンスボディ

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

エラー時の挙動

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

Webhook 機能