Webhookは、HTTP POSTリクエストを通じてアプリケーションにリアルタイムイベント通知を配信します。支払い、ポリシー違反、エージェントステータスの変更、x402セッションイベントに対応するために使用します。
Webhookの設定
SDK経由
const webhook = await aw.webhooks.create({
url: "https://your-app.com/webhooks/agentwallex",
events: [
"payment.completed",
"payment.failed",
"agent.frozen",
"policy.violated",
],
secret: "whsec_your_signing_secret",
});
API経由
curl -X POST https://api.agentwallex.com/api/v1/webhooks \
-H "X-API-Key: awx_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/agentwallex",
"events": ["payment.completed", "payment.failed", "agent.frozen", "policy.violated"],
"secret": "whsec_your_signing_secret"
}'
イベントタイプ
| イベント | 説明 |
|---|
payment.completed | トランザクションがオンチェーンで確認されました |
payment.failed | トランザクションが失敗またはリバートしました |
payment.pending | トランザクションが送信され、確認待ちです |
agent.frozen | エージェントウォレットが凍結されました |
agent.unfrozen | エージェントウォレットが凍結解除されました |
policy.violated | トランザクションがポリシーエンジンによって拒否されました |
x402.session.expired | x402セッションの予算またはTTLを超過しました |
approval.requested | 高額トランザクションが人間の承認を待っています |
Webhookペイロード
すべてのWebhook配信には、この構造のJSONペイロードが含まれます：
{
"id": "evt_abc123",
"type": "payment.completed",
"created_at": "2025-06-15T14:30:00Z",
"data": {
"transaction_id": "tx_xyz789",
"agent_id": "agent_abc123",
"amount": "50.00",
"token": "USDC",
"chain": "eip155:8453",
"hash": "0xabc...def",
"status": "confirmed"
}
}
署名検証
すべてのWebhook配信には検証用の署名ヘッダーが含まれます。Webhookイベントを処理する前に必ず署名を検証してください。
仕組み
AgentWallexは、登録時に提供されたシークレットを使用して各Webhookペイロードに署名します。署名はX-AgentWallex-Signatureヘッダーで送信されます。
検証の例
import crypto from "crypto";
function verifyWebhookSignature(
payload: string,
signature: string,
secret: string
): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
// In your webhook handler
app.post("/webhooks/agentwallex", (req, res) => {
const signature = req.headers["x-agentwallex-signature"] as string;
const isValid = verifyWebhookSignature(
JSON.stringify(req.body),
signature,
"whsec_your_signing_secret"
);
if (!isValid) {
return res.status(401).send("Invalid signature");
}
// Process the event
const event = req.body;
console.log(`Received ${event.type} event`);
res.status(200).send("OK");
});
タイミング攻撃を防ぐために、署名の検証には常に定数時間比較（例：timingSafeEqualやhmac.compare_digest）を使用してください。
Webhookのテスト
Webhookエンドポイントにテストイベントを送信します：
curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
-H "X-API-Key: awx_your_api_key"
配信履歴の表示
Webhookの配信履歴を確認します：
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
-H "X-API-Key: awx_your_api_key"
Webhookの管理
# List all webhooks
GET /webhooks
# Get a specific webhook
GET /webhooks/:id
# Update a webhook
PUT /webhooks/:id
# Delete a webhook
DELETE /webhooks/:id
ベストプラクティス
Webhook配信には5秒以内に2xxステータスコードで応答してください。ハンドラーで重い処理が必要な場合は、Webhookを即座に確認してから非同期で処理してください。
- 常に署名を検証する — イベントを処理する前に必ず検証してください。
- 重複を処理する — Webhook配信はリトライされる場合があります。冪等性のために
idフィールドを使用してください。
- 200を素早く返す — 重い処理を行う前に受信を確認してください。
- 配信失敗を監視する — 配信エンドポイントで失敗した配信を確認してください。
- 特定のイベントフィルターを使用する — すべてのイベントを受信するのではなく、必要なイベントのみを購読してください。
