Webhook を使用すると、AI タスクが success または error ステータスで完了したときに、アプリケーションが非同期通知を受信できます。通知はあなたが管理する HTTP エンドポイントに送信され、Standard Webhooks Specification に準拠しています。
HMAC-SHA256 署名方式の Webhook シークレットを使用しています。Webhook シークレットは base64 エンコードされ、識別しやすいよう whsec_ がプレフィックスとして付与されています。
Webhook シークレットの例:
whsec_NDQzMzYxNzkzMzE0NjYyNDM6OTIxOTcwNDIxODQ
Standard Webhooks Library の公式実装の使用を推奨します。署名検証の詳細を気にする必要はありません。
公式実装を使用することで、安全かつ正確な署名検証が保証されます。
Webhook シークレットの仕組みを理解してください。Signature scheme の Symmetric 部分を参照してください。
署名入力を署名する際は、whsec_ プレフィックスを除去し、残りの文字列を base64 デコードしてシークレットの実際のバイトを取得してから、HMAC-SHA256 ハッシュを実行します。
POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0={
"created_at": 1761112848,
"data": {
"task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
"task_status": "success"
}
}Webhook 配信の一意な識別子です。 この値はリトライ間で一貫しており、冪等性処理に使用すべきです。
Webhook が送信されたときの Unix エポックタイムスタンプ（秒）です。
'v1' の後にカンマ (,) が続き、その後に base64 エンコードされた HMAC-SHA256 署名が続きます。
'v1' は署名方式のバージョンを示し、現在サポートされている唯一のバージョンです。
base64 エンコードされた HMAC-SHA256 署名は、Webhook シークレットを使用して署名入力を署名した結果です。
署名入力形式:
{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}署名済みコンテンツの例:
msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}タスクが完了した時刻を示す Unix エポックタイムスタンプ（秒）です。
イベントペイロードを含みます。
| フィールド | 説明 |
|---|---|
task_id | タスク作成時に返されたタスク識別子です。この ID を使用して最終的なタスク結果をクエリできます。 |
task_status | タスク完了ステータス。可能な値: success、error。 |
サーバーに Webhook エンドポイントを準備する。 エンドポイントが
POSTリクエストを受け入れ、HTTPS 経由でアクセス可能であることを確認してください。API Console で Webhook を作成する。
AI タスクを実行し、
task_idを記録する。Webhook 通知を処理し、
task_idを使用してタスク結果を取得する。
API Console の Webhook 管理ページにアクセスします:
https://yce.makeupar.com/api-console/en/webhook/
最大 10 の Webhook エンドポイント を同時に設定できます。
Webhook シークレットは webhook-signature の検証に使用されます。 安全に保管し、公開しないでください。
Standard Webhooks Library の公式実装の使用を推奨します:
これにより、安全かつ正確な署名検証が保証されます。
Standard Webhooks Simulator を使用してペイロードのテストやデバッグもできます:
https://www.standardwebhooks.com/simulate
Webhook リクエスト例を検討します:
POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=リクエストボディ:
{
"created_at": 1761112848,
"data": {
"task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
"task_status": "success"
}
}署名入力形式は次のようになります:
{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}署名済みコンテンツの例:
msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}受信した webhook-signature を使用して、Webhook シークレットキーで HMAC-SHA256 暗号化された署名済みコンテンツを検証します。 例:
v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=