Webhooks

概述

Webhooks 通过 HTTP POST 请求向您的应用程序发送实时事件通知。使用它们来响应支付、策略违规、代理状态变更和 x402 会话事件。

设置 Webhooks

通过 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");
});

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

验证签名时请始终使用常量时间比较（例如 timingSafeEqual 或 hmac.compare_digest），以防止时序攻击。

测试 Webhooks

向您的 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"

管理 Webhooks

# List all webhooks
GET /webhooks

# Get a specific webhook
GET /webhooks/:id

# Update a webhook
PUT /webhooks/:id

# Delete a webhook
DELETE /webhooks/:id

最佳实践

在 5 秒内以 2xx 状态码响应 Webhook 投递。如果您的处理程序需要进行较重的处理，请立即确认 Webhook 并异步处理。

始终验证签名 — 在处理事件之前验证签名。
处理重复投递 — Webhook 投递可能会被重试。使用 id 字段实现幂等性。
快速返回 200 — 在进行较重处理之前确认接收。
监控投递失败 — 检查投递端点以了解失败的投递。
使用特定的事件过滤器 — 仅订阅您需要的事件，而非接收所有事件。

快速入门

平台

核心功能

使用指南

概述

设置 Webhooks

通过 SDK

通过 API

事件类型

Webhook 载荷

签名验证

工作原理

验证示例

测试 Webhooks

查看投递记录

管理 Webhooks

最佳实践

​概述

​设置 Webhooks

​通过 SDK

​通过 API

​事件类型

​Webhook 载荷

​签名验证

​工作原理

​验证示例

​测试 Webhooks

​查看投递记录

​管理 Webhooks

​最佳实践

概述

设置 Webhooks

通过 SDK

通过 API

事件类型

Webhook 载荷

签名验证

工作原理

验证示例

测试 Webhooks

查看投递记录

管理 Webhooks

最佳实践