eformsign Webhook の使い方

eformsign でイベントが発生した時、そのイベント情報を顧客のシステム/サービスに通知する機能です。Webhook を設定すると、顧客の Webhook endpoint にそのイベント情報を HTTP POST 形式で通知します。

ちなみに

Webhook の endpoint とは、顧客の client callback URL を意味します。Open API を持続的に呼び出して変更内容をチェックする方式(polling)に比べ、不要な呼び出しをせず eformsign 上のイベントについての情報を取得できます。

始めてみよう

Webhook キーの発行

  1. eformsign に代表管理者としてログインし、左側のメニューから コネクト > API/Webhook ページに移動します。

コネクト > API/Webhook メニューの位置
  1. Webhook タブを選択し、Webhookの作成 ボタンをクリックします。

「Webhookの作成」ボタン
  1. Webhook の作成 ポップアップに名前、Webhook の URL、アクティブ状態、適用対象を選択し、登録 ボタンをクリックします。

「Webhookの作成」ポップアップ
  1. 作成された Webhook リストから キーを表示 ボタンをクリックして Webhook の公開鍵を確認します。

「キーを表示」ボタンの位置 Webhookのキーを確認

注釈

キーを再発行 ボタンをクリックすると、その Webhook の公開鍵が再発行され、以前のキーは使用できなくなります。

注釈

Webhook 情報の修正

作成された Webhook リストから 修正 ボタンをクリックして Webhook 情報を変更することができます。

注釈

Webhook の削除

作成された Webhook リストから 削除 ボタンをクリックして Webhook を削除することができます。

  1. 作成された Webhook リストからテスト ボタンをクリックすると、テスト Webhook を送信して結果値を返します。

Webhook テスト 確認

次はテストのための json ファイルです。

{
"webhook_id" : "Webhook ID",
"webhook_name" : "Webhookの名前",
"company_id" : "会社ID",
"event_type" : “document”,
"document" : {
  "id" : “test_doc_id”,
   "template_id" : “test_template_id”,
   "template_version" : “1”,
   "document_history_id" : “test_document_history_id”,
   "doc_status" : “doc_create”,
   "editor_id" : "ユーザーID",
   "updated_date" : "現在時間(UTC Long)"
}
}
Test URL : WebhookのURL

署名の登録

署名の登録方法については、Java、Python、PHPの各言語に分けて説明します。

Java

eformsign サーバーから送られたイベント情報を Webhook キーの発行で発行した公開鍵で検証し、 eformsign で正常に呼び出したイベントであるか検証します。

注釈

署名のアルゴリズムは SHA256withECDSA を使用します。

Python

キーフォーマット処理用のライブラリーを使用する必要があります。作業を開始する前に、次のコマンドを実行してライブラリーをインストールしてください。

pip install https://github.com/warner/python-ecdsa/archive/master.zip

PHP

次の例題の keycheck.inc.php、test.php ファイルを同じパスに保存してから例題を実施してください。

例題

次は各言語の例題です。

import java.io.*;
import java.math.BigInteger;
import java.security.*;
import java.security.spec.X509EncodedKeySpec;

....
/**
 *  requestでheaderとbodyを読み取ります。
 *
 */


//1. get eformsign signature
//eformsignSignatureはrequest headerに含まれています。
String eformsignSignature = request.getHeader("eformsign_signature");


//2. get request body data
// eformsign signature 検証のため body のデータを String に変換します。
String eformsignEventBody = null;
StringBuilder stringBuilder = new StringBuilder();
BufferedReader bufferedReader = null;

try {
    InputStream inputStream = request.getInputStream();
    if (inputStream != null) {
        bufferedReader = new BufferedReader(new InputStreamReader(inputStream));
        char[] charBuffer = new char[128];
        int bytesRead = -1;
        while ((bytesRead = bufferedReader.read(charBuffer)) > 0) {
            stringBuilder.append(charBuffer, 0, bytesRead);
        }
    }
 } catch (IOException ex) {
    throw ex;
 } finally {
    if (bufferedReader != null) {
        try {
            bufferedReader.close();
        } catch (IOException ex) {
            throw ex;
        }
    }
 }
eformsignEventBody = stringBuilder.toString();




//3. publicKey設定
String publicKeyHex = "発行したPublic Key(String)";
KeyFactory publicKeyFact = KeyFactory.getInstance("EC");
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(new BigInteger(publicKeyHex,16).toByteArray());
PublicKey publicKey = publicKeyFact.generatePublic(x509KeySpec);

//4. verify
Signature signature = Signature.getInstance("SHA256withECDSA");
signature.initVerify(publicKey);
signature.update(eformsignEventBody.getBytes("UTF-8"));
if(signature.verify(new BigInteger(eformsignSignature,16).toByteArray())){
    //verify success
    System.out.println("verify success");
    /*
     * ここでイベントに応じた処理を行います。
     */
}else{
    //verify fail
    System.out.println("verify fail");
}
import hashlib
        import binascii

        from ecdsa import VerifyingKey, BadSignatureError
        from ecdsa.util import sigencode_der, sigdecode_der
        from flask import request


        ...
        # requestでheaderとbodyを読み取ります。
        # 1. get eformsign signature
        # eformsignSignatureはrequest headerに含まれています。
        eformsign_signature_str= request.headers['eformsign_signature']
        eformsign_signature = binascii.unhexlify(eformsign_signature_str)


        # 2. get request body data
        # eformsign signature検証のためbodyのデータをStringに変換します。
        data = request.data


        # 3. publicKey設定
        publicKeyHex = "発行したpublic key"
        publickey = VerifyingKey.from_der(binascii.unhexlify(publicKeyHex))


        # 4. verify
        try:
            if publickey.verify(eformsign_signature, data, hashfunc=hashlib.sha256, sigdecode=sigdecode_der):
                print("verify success")
                # ここでイベントに応じた処理を行います。
        except BadSignatureError:
            print("verify fail")
<?php
namespace eformsignECDSA;

class PublicKey
{

    function __construct($str)
    {
        $pem_data = base64_encode(hex2bin($str));
        $offset = 0;
        $pem = "-----BEGIN PUBLIC KEY-----\n";
        while ($offset < strlen($pem_data)) {
            $pem = $pem . substr($pem_data, $offset, 64) . "\n";
            $offset = $offset + 64;
        }
        $pem = $pem . "-----END PUBLIC KEY-----\n";
        $this->openSslPublicKey = openssl_get_publickey($pem);
    }
}

function Verify($message, $signature, $publicKey)
{
    return openssl_verify($message, $signature, $publicKey->openSslPublicKey, OPENSSL_ALGO_SHA256);
}
?>
<?php
require_once __DIR__ . '/keycheck.inc.php';
use eformsignECDSA\PublicKey;

define('PUBLIC_KEY', '発行したpublic keyを入力してください。');
...
/*
 *  request で header と body を読み取ります。
 *
 */


//1. get eformsign signature
//eformsignSignatureはrequest headerに含まれています。
$eformsignSignature = $_SERVER['HTTP_eformsign_signature'];


//2. get request body data
// eformsign signature検証のためbodyのデータを読み取ります。
$eformsignEventBody = json_decode(file_get_contents('php://input'), true);


//3. publicKey設定
$publicKey = new PublicKey(PUBLIC_KEY);


//4. verify
$ret = - 1;
$ret = eformsignECDSA\Verify(MESSAGE, $eformsignSignature, $publicKey);

if ($ret == 1) {
    print 'verify success' . PHP_EOL;
    /*
     * ここでイベントに応じた処理を行います。
     */
} else {
    print 'verify fail' . PHP_EOL;
}
 ...

?>

テスト

作成した eformsign_signature をテストしてみましょう。

次の eformsign_signature の作成・検証用のサンプルは、Open API または Webhook の署名値を作成および検証するためのテストサンプルのソースコードです。

注釈

サンプルキーを使用しているため、実際の環境では正常動作しません。例題で作成した署名値の検証用途としてのみご利用ください。

Java

次のサンプルキーで署名および検証テストを行ってください。

Python

キーフォーマット処理用のライブラリーを使用する必要があります。作業を開始する前に、次のコマンドを実行してライブラリーをインストールしてください。

pip install https://github.com/warner/python-ecdsa/archive/master.zip

PHP

次の例題の keycheck.inc.php、test.php ファイルを同じパスに保存してから例題を実施してください。

例題

次は各言語のテストキーと例題です。

String privateKeyHex = "3041020100301306072a8648ce3d020106082a8648ce3d0301070427302502010104207eae51d5e4272ebb3fe2701d25026a8c2850965981fb2efa68c8db48b32ede07";
String publicKeyHex = "3059301306072a8648ce3d020106082a8648ce3d030107034200045ac8a472cee38601e99b2a2d731c958e738eee1ee6aca28f6f5637f231e9a8444f3cb80d9ce6c5bace1d0e71167673ff81743e0ea811ebd999f2f314f1d0a676";     //private key
KeyFactory privateKeyFact = KeyFactory.getInstance("EC");
PKCS8EncodedKeySpec psks8KeySpec = new PKCS8EncodedKeySpec(new BigInteger(privateKeyHex,16).toByteArray());
PrivateKey privateKey = privateKeyFact.generatePrivate(psks8KeySpec);

//signature
String testData = "{\"test\":\"signature test\"}";
Signature ecdsa = Signature.getInstance("SHA256withECDSA");
ecdsa.initSign(privateKey);
ecdsa.update(testData.getBytes("UTF-8"));
String eformsign_signature = new BigInteger(ecdsa.sign()).toString(16);
System.out.println("data : "+testData);
System.out.println("eformsign_signature : "+eformsign_signature);

//public key
KeyFactory publicKeyFact = KeyFactory.getInstance("EC");
X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(new BigInteger(publicKeyHex,16).toByteArray());
PublicKey publicKey = publicKeyFact.generatePublic(x509KeySpec);


//verify
Signature signature = Signature.getInstance("SHA256withECDSA");
signature.initVerify(publicKey);
signature.update(testData.getBytes("UTF-8"));
if(signature.verify(new BigInteger(eformsign_signature,16).toByteArray())){
    //verify success
    System.out.println("verify success");
}else{
    //verify fail
    System.out.println("verify fail");
}
import hashlib
import binascii

from ecdsa import VerifyingKey, BadSignatureError
from ecdsa.util import sigencode_der, sigdecode_der
from flask import request

privateKeyHex = "3041020100301306072a8648ce3d020106082a8648ce3d0301070427302502010104207eae51d5e4272ebb3fe2701d25026a8c2850965981fb2efa68c8db48b32ede07"
publicKeyHex = "3059301306072a8648ce3d020106082a8648ce3d030107034200045ac8a472cee38601e99b2a2d731c958e738eee1ee6aca28f6f5637f231e9a8444f3cb80d9ce6c5bace1d0e71167673ff81743e0ea811ebd999f2f314f1d0a676"

data = "{\"test\":\"signature test\"}"

sk = SigningKey.from_der(binascii.unhexlify(privateKeyHex))
vk = VerifyingKey.from_der(binascii.unhexlify(publicKeyHex))

signature = sk.sign(data.encode('utf-8'), hashfunc=hashlib.sha256, sigencode=sigencode_der)

print("data: " + data)
print("eformsign_signature : " + binascii.hexlify(signature).decode('utf-8'))

try:
    if vk.verify(signature, data.encode('utf-8'), hashfunc=hashlib.sha256, sigdecode=sigdecode_der):
        print("verify success")
except BadSignatureError:
    print("verify fail")
<?php
namespace eformsignECDSA;

class PublicKey
{

    function __construct($str)
    {
        $pem_data = base64_encode(hex2bin($str));
        $offset = 0;
        $pem = "-----BEGIN PUBLIC KEY-----\n";
        while ($offset < strlen($pem_data)) {
            $pem = $pem . substr($pem_data, $offset, 64) . "\n";
            $offset = $offset + 64;
        }
        $pem = $pem . "-----END PUBLIC KEY-----\n";
        $this->openSslPublicKey = openssl_get_publickey($pem);
    }
}

class PrivateKey
{

    function __construct($str)
    {
        $pem_data = base64_encode(hex2bin($str));
        $offset = 0;
        $pem = "-----BEGIN EC PRIVATE KEY-----\n";
        while ($offset < strlen($pem_data)) {
            $pem = $pem . substr($pem_data, $offset, 64) . "\n";
            $offset = $offset + 64;
        }
        $pem = $pem . "-----END EC PRIVATE KEY-----\n";
        $this->openSslPrivateKey = openssl_get_privatekey($pem);
    }
}

function Sign($message, $privateKey)
{
    openssl_sign($message, $signature, $privateKey->openSslPrivateKey, OPENSSL_ALGO_SHA256);
    return $signature;
}

function Verify($message, $signature, $publicKey)
{
    return openssl_verify($message, $signature, $publicKey->openSslPublicKey, OPENSSL_ALGO_SHA256);
}
?>
<?php
require_once __DIR__ . '/keycheck.inc.php';

define('PRIVATE_KEY', '3041020100301306072a8648ce3d020106082a8648ce3d0301070427302502010104207eae51d5e4272ebb3fe2701d25026a8c2850965981fb2efa68c8db48b32ede07');
define('PUBLIC_KEY', '3059301306072a8648ce3d020106082a8648ce3d030107034200045ac8a472cee38601e99b2a2d731c958e738eee1ee6aca28f6f5637f231e9a8444f3cb80d9ce6c5bace1d0e71167673ff81743e0ea811ebd999f2f314f1d0a676');
define('MESSAGE', '{"test":"signature test"}');

use eformsignECDSA\PrivateKey;
use eformsignECDSA\PublicKey;

$sk = new PrivateKey(PRIVATE_KEY);
$vk = new PublicKey(PUBLIC_KEY);

$signature = eformsignECDSA\Sign(MESSAGE, $sk);

print 'data: ' . MESSAGE . PHP_EOL;
print 'eformsign_signature : ' . bin2hex($signature) . PHP_EOL;

$ret = - 1;
$ret = eformsignECDSA\Verify(MESSAGE, $signature, $vk);

if ($ret == 1) {
    print 'verify success' . PHP_EOL;
} else {
    print 'verify fail' . PHP_EOL;
}

?>

Webhook 提供リスト

次の Webhook を設定すると、そのイベントが発生するとき、設定した Webhook endpoint に変更情報を受信することができます。

現在提供している Webhookは次のとおりです。

POST: /webhook ウェブフック送信

各 eformsign Webhook についての詳しい説明は で確認することができます。

Webhook についての情報

eformsign は Webhook イベントとして 文書 イベントと PDF 作成 イベントを提供しています。

文書イベント

eformsign で文書の作成または状態の変更があるときに発生するイベントです。

Name

Type

説明

id

String

文書のID

template_id

String

テンプレートのID

template_name

String

テンプレートの名前

template_version

String

テンプレートのバージョン

workflow_seq

int

ワークフローの順序

workflow_name

String

ワークフローの名前

history_id

String

文書履歴のID

status

String

文書の状態

editor_id

String

作成者のID

updated_date

long

文書の変更時間

イベントデータのうち、文書の状態を表す status の意味については、次をご覧ください。

Name

説明

doc_create

作成

doc_tempsave

下書き保存

doc_request_approval

決裁の依頼

doc_accept_approval

決裁の承認

doc_reject_approval

決裁の返戻

doc_request_external

外部受信者に依頼

doc_remind_external

外部受信者に再依頼

doc_open_external

外部受信者が閲覧

doc_accept_external

外部受信者が承認

doc_reject_external

外部受信者が返戻

doc_request_internal

内部受信者に依頼

doc_accept_internal

内部受信者が承認

doc_reject_internal

内部受信者が返戻

doc_tempsave_internal

内部受信者が下書き保存

doc_cancel_request

依頼の無効化

doc_reject_request

返戻の依頼

doc_decline_cancel_request

返戻依頼の拒否

doc_delete_request

削除の依頼

doc_decline_delete_request

削除依頼の拒否

doc_deleted

削除

doc_complete

完了

PDF 作成イベント

eformsign で文書の PDF ファイルを作成するときに発生するイベントです。

Name

Type

説明

document_id

String

文書のID

template_id

String

テンプレートのID

template_name

String

テンプレートの名前

template_version

String

テンプレートのバージョン

workflow_seq

int

ワークフローの順序

workflow_name

String

ワークフローの名前

document_history_id

String

文書履歴のID

document_status

String

文書の状態

イベントデータのうち、文書の状態を表す status の意味については、をご覧ください。