Logo Site EngageLab Mark Colored Transparentドキュメント
OTP
ドキュメントホーム
ドキュメントAPI リファレンス
検索
ログイン
API リファレンス/コールバック設定
API リファレンスコールバック設定...

コールバック設定の説明

最新更新：7日前

このセクションでは、EngageLab OTP のコールバックアドレスと関連するセキュリティ検証機構を設定し、コールバックデータの信頼性とセキュリティを確保する方法を説明します。

コールバックアドレスの設定と検証

コールバックアドレスを設定すると、EngageLab OTP は自動的にそのアドレスへ HTTP POST リクエストを送信し、インターフェースの可用性を検証します。お客様のサービスは 3 秒以内に HTTP 200 ステータスコードを返す必要があります。そうでない場合、システムはそのアドレスを利用不可とみなします。

注意:
コールバックデータを正常に受信できるよう、119.8.170.74 と 114.119.180.30 をサーバーのファイアウォールのホワイトリストに追加してください。

リクエスト例

コールバックアドレスが https://example.engagelabotp.callback.com であると仮定すると、システムは次のリクエストを送信します。

curl -X POST https://example.engagelabotp.callback.com -d '{}'
              
              curl -X POST https://example.engagelabotp.callback.com -d '{}'
このコードブロックはフローティングウィンドウ内に表示されます

レスポンス要件

お客様のサービスは HTTP 200 ステータスコードを返すだけでよく、コンテンツを返す必要はありません。例:

HTTP/1.1 200 OK Content-Length: 0
              
              HTTP/1.1 200 OK
Content-Length: 0
このコードブロックはフローティングウィンドウ内に表示されます

注意:
コールバックアドレスの検証は HTTP ステータスコードのみを判定し、特定のメッセージ内容を返す必要はありません。お客様のサービスインターフェースが 3 秒以内に正しく 200 を応答できることを確認してください。

コールバックのセキュリティ機構

コールバックデータのセキュリティと送信元の信頼性を確保するため、EngageLab OTP は複数のセキュリティ検証方式をサポートしています。

ユーザー名とシークレットによる検証（任意）

  • 任意の設定です。ユーザー名を設定する場合は、シークレットも必ず設定する必要があります。
  • 設定後、EngageLab は各コールバックリクエストの HTTP ヘッダーに X-CALLBACK-ID フィールドを次の形式で追加します。
X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
              
              X-CALLBACK-ID: timestamp={timestamp};nonce={nonce};username={username};signature={signature}
このコードブロックはフローティングウィンドウ内に表示されます
  • 各項目の意味:
    • timestamp: コールバック送信時のタイムスタンプ
    • nonce: ランダムな数値
    • username: お客様が設定したユーザー名
    • signature: 署名情報。次のように計算されます

署名の計算方法（Python の例）

import hashlib, hmac def verify(username, secret, timestamp, nonce, signature): return signature == hmac.new( key=secret.encode(), msg=f'{timestamp}{nonce}{username}'.encode(), digestmod=hashlib.sha256 ).hexdigest()
              
              import hashlib, hmac
def verify(username, secret, timestamp, nonce, signature):
    return signature == hmac.new(
        key=secret.encode(),
        msg=f'{timestamp}{nonce}{username}'.encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
このコードブロックはフローティングウィンドウ内に表示されます
  • サーバー側では上記の方法でコールバックリクエストの正当性を検証できます。

Authorization 認証（任意）

  • コールバックインターフェースで認証（Basic Auth、Bearer Token など）が必要な場合、設定時に Authorization 情報を入力できます。
  • EngageLab はリクエスト時にこの Authorization フィールドを自動的に付与するため、お客様のサービスでリクエストの送信元を検証しやすくなります。

コールバックイベントの説明

メッセージステータス

メッセージステータスは、各メッセージのライフサイクルにおけるステータス変化を追跡するために使用されます。メッセージの送信、配信、検証などの各段階の進捗状況をリアルタイムに把握でき、統計分析、例外処理、ユーザー体験の最適化に役立ちます。

イベント識別子 説明
plan メッセージの送信が予定され、待機キューに入った
target_valid 宛先番号が有効
target_invalid 宛先番号が無効
sent メッセージの送信に成功
sent_failed メッセージの送信に失敗
delivered メッセージがユーザー端末に配信された
delivered_failed メッセージは送信されたが、ユーザー端末への配信に失敗
verified ユーザーが OTP 検証を正常に完了
verified_failed ユーザーの検証に失敗
verified_timeout ユーザーが指定時間内に検証を完了せず、タイムアウト

コールバックデータ構造

外側の構造

{ "total": 1, "rows": [ { // ReportLifecycle object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // ReportLifecycle object
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます
フィールド名 型 説明
total int 今回のコールバックに含まれるデータ件数
rows array ライフサイクルステータスデータの配列

ReportLifecycle オブジェクト

フィールド名 型 説明
message_id string メッセージの一意な ID
to string 受信者の番号
server string サービス種別（例: otp）
channel string チャネル種別
itime int64 コールバックのタイムスタンプ（秒）
custom_args object カスタムパラメータ（送信時に渡した場合に返却）
status object ステータス詳細オブジェクト

status オブジェクト

フィールド名 型 説明
message_status string 現在のメッセージステータス（下表参照）
status_data object ステータスデータオブジェクト
billing object 課金情報オブジェクト（課金時に返却）
error_code int エラーコード。0 はエラーなしを意味する
error_detail object エラー詳細（エラー発生時に返却）

status_data オブジェクト

フィールド名 型 説明
msg_time int64 メッセージ作成タイムスタンプ（秒）
message_id string メッセージ ID
current_send_channel string 現在の送信チャネル名
template_key string テンプレート設定の Key
business_id string ビジネス ID

billing オブジェクト（課金時に返却）

フィールド名 型 説明
cost float64 費用額
currency string 通貨。固定値 "USD"

通常、billing 情報を含むのは sent 段階のメッセージのみです。

error_detail オブジェクト（エラー発生時に返却）

フィールド名 型 説明
message string エラーメッセージの説明

例: メッセージの送信に成功

{ "total": 1, "rows": [ { "message_id": "123456789", "to": "+6598765432", "server": "sms", "channel": "sms", "itime": 1701234567, "custom_args": { "order_id": "ORDER123", "user_id": "USER456" }, "status": { "message_status": "sent", "status_data": { "msg_time": 1701234560, "message_id": "123456789", "current_send_channel": "CHANNEL_A", "template_key": "verify_code", "business_id": "1001" }, "billing": { "cost": 0.005, "currency": "USD" }, "error_code": 0 } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456789",
      "to": "+6598765432",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234567,
      "custom_args": {
        "order_id": "ORDER123",
        "user_id": "USER456"
      },
      "status": {
        "message_status": "sent",
        "status_data": {
          "msg_time": 1701234560,
          "message_id": "123456789",
          "current_send_channel": "CHANNEL_A",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "billing": {
          "cost": 0.005,
          "currency": "USD"
        },
        "error_code": 0
      }
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます

例: メッセージの送信に失敗

{ "total": 1, "rows": [ { "message_id": "123456790", "to": "+6598765433", "server": "sms", "channel": "sms", "itime": 1701234568, "status": { "message_status": "sent_fail", "status_data": { "msg_time": 1701234561, "message_id": "123456790", "current_send_channel": "CHANNEL_B", "template_key": "verify_code", "business_id": "1001" }, "error_code": 4001, "error_detail": { "message": "Invalid phone number" } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "message_id": "123456790",
      "to": "+6598765433",
      "server": "sms",
      "channel": "sms",
      "itime": 1701234568,
      "status": {
        "message_status": "sent_fail",
        "status_data": {
          "msg_time": 1701234561,
          "message_id": "123456790",
          "current_send_channel": "CHANNEL_B",
          "template_key": "verify_code",
          "business_id": "1001"
        },
        "error_code": 4001,
        "error_detail": {
          "message": "Invalid phone number"
        }
      }
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます

メッセージ通知

メッセージ通知とは、システムレベルのビジネスイベントやアラートを指します。サービスの稼働状況、残高、テンプレート審査などの重要情報に注意を促し、ビジネス側がタイムリーに対応したりリスクを早期に把握したりするのに役立ちます。

イベント識別子 説明
insufficient_verification_rate 検証率が設定したしきい値を下回った
insufficient_balance アカウント残高が不足している
template_audit_result テンプレート審査結果の通知

例

{ "total": 1, "rows": [{ "server": "otp", "itime": 1712458844, "notification": { "event": "insufficient_balance", "notification_data": { "business_id": "1744569418236633088", "remain_balance": -0.005, // 現在の残高; "balance_threshold": 2 // アラートのしきい値; } } }] }
              
              {
    "total": 1,
    "rows": [{
        "server": "otp",
        "itime": 1712458844,
        "notification": {
            "event": "insufficient_balance",
            "notification_data": {
                "business_id": "1744569418236633088",
                "remain_balance": -0.005,                    // 現在の残高;
                "balance_threshold": 2                       // アラートのしきい値;
            }
        }
    }]
}
このコードブロックはフローティングウィンドウ内に表示されます

メッセージレスポンス

メッセージレスポンスは主に、ユーザーや外部システムとのやり取りにおけるコールバック応答イベントを指します。

イベント識別子 説明
uplink_message ユーザーが SMS などで返信したアップリンクメッセージの内容

例

{ "total": 1, "rows": [ { "server": "otp", "itime": 1741083306, "message_id": "0", "business_id": "0", "response": { "event": "uplink_message", "response_data": { "message_sid": "SM1234567890", "account_sid": "AC1234567890", "from": "+1234567890", "to": "+0987654321", "body": "Hello, it's time to struggle!" } } } ] }
              
              {
    "total": 1,
    "rows": [
        {
            "server": "otp",
            "itime": 1741083306,
            "message_id": "0",
            "business_id": "0",
            "response": {
                "event": "uplink_message",
                "response_data": {
                    "message_sid": "SM1234567890",
                    "account_sid": "AC1234567890",
                    "from": "+1234567890",
                    "to": "+0987654321",
                    "body": "Hello, it's time to struggle!"
                }
            }
        }
    ]
}
このコードブロックはフローティングウィンドウ内に表示されます

システムイベント

システムイベントは、アカウント、テンプレート、API 呼び出しなどに関連する操作行為を対象とします。アカウントのログイン、キーの変更、API 呼び出しなどの重要な操作の監視、監査、自動処理に役立ちます。

イベント識別子 説明
account_login アカウントのログイン関連の操作通知
key_manage キーの変更・管理関連の操作通知
msg_history メッセージ履歴の照会関連の操作通知
template_manage テンプレートの追加・変更・削除の操作通知
api_call API インターフェースの呼び出し関連の操作通知

コールバックデータ構造

外側の構造

{ "total": 1, "rows": [ { // System event object } ] }
              
              {
  "total": 1,
  "rows": [
    {
      // System event object
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます
フィールド 型 説明
total int64 今回のコールバックのイベント総数
rows array システムイベントオブジェクトの配列

システムイベントオブジェクト

フィールド 型 説明
server string 固定値 "otp"
itime int64 イベント発生タイムスタンプ（秒）
system_event object システムイベントの内容

system_event オブジェクト

フィールド 型 説明
event string イベント種別
data object イベントデータ

data オブジェクト

フィールド 型 説明
business_id string ビジネス ID
org_id string 組織 ID
operator object 操作者情報

operator オブジェクト

フィールド 型 説明
email string 操作者のメール（存在する場合）
api_key string API キー（存在する場合）
ip_address string 操作元 IP

リクエスト構造

{ "total": 1, "rows": [ { "server": "otp", "itime": 1694012345, "system_event": { "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "api_key": "api-xxxx", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } } } ] }
              
              {
  "total": 1,
  "rows": [
    {
      "server": "otp",
      "itime": 1694012345,
      "system_event": {
        "event": "account_login",
        "data": {
          "business_id": "123",
          "org_id": "org-abc",
          "operator": {
            "email": "foo@example.com",
            "api_key": "api-xxxx",
            "ip_address": "1.2.3.4"
          },
          "account_login": {
            "action": "login_success"
          }
        }
      }
    }
  ]
}
このコードブロックはフローティングウィンドウ内に表示されます

アカウントログインイベント

フィールド 型 説明
action string login_success / login_failed / logout
fail_reason string ログイン失敗の理由。login_failed の場合のみ返却

例

{ "event": "account_login", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "account_login": { "action": "login_success" } } }
              
              {
  "event": "account_login",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "account_login": {
      "action": "login_success"
    }
  }
}
このコードブロックはフローティングウィンドウ内に表示されます

テンプレート管理イベント

フィールド 型 説明
action string create template / update template / delete template
template_id string テンプレート ID
template_name string テンプレート名

例

{ "event": "template_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "template_manage": { "action": "update template", "template_id": "tmpl-456", "template_name": "Verification Code" } } }
              
              {
  "event": "template_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "template_manage": {
      "action": "update template",
      "template_id": "tmpl-456",
      "template_name": "Verification Code"
    }
  }
}
このコードブロックはフローティングウィンドウ内に表示されます

キー管理イベント

フィールド 型 説明
action string 列挙値:
create api_key: API キーの作成
update api_key: API キーの更新
delete api_key: API キーの削除
view api_secret: API シークレットの表示
api_key string API キー
description string 説明（任意）

例

{ "event": "key_manage", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "email": "foo@example.com", "ip_address": "1.2.3.4" }, "key_manage": { "action": "create", "api_key": "apikey-789", "description": "New Key" } } }
              
              {
  "event": "key_manage",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "email": "foo@example.com",
      "ip_address": "1.2.3.4"
    },
    "key_manage": {
      "action": "create",
      "api_key": "apikey-789",
      "description": "New Key"
    }
  }
}
このコードブロックはフローティングウィンドウ内に表示されます

API 呼び出しイベント

フィールド 型 説明
api_path string API パス
method string HTTP メソッド

例

{ "event": "api_call", "data": { "business_id": "123", "org_id": "org-abc", "operator": { "api_key": "apikey-789", "ip_address": "1.2.3.4" }, "api_call": { "api_path": "/api/v1/messages/send", "method": "POST" } } }
              
              {
  "event": "api_call",
  "data": {
    "business_id": "123",
    "org_id": "org-abc",
    "operator": {
      "api_key": "apikey-789",
      "ip_address": "1.2.3.4"
    },
    "api_call": {
      "api_path": "/api/v1/messages/send",
      "method": "POST"
    }
  }
}
このコードブロックはフローティングウィンドウ内に表示されます
Icon Solid Transparent White Qiyu
お問い合わせ