> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentwallex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> 接收支付、策略违规和代理事件的实时通知。

## 概述

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

## 设置 Webhooks

### 通过 SDK

```typescript theme={null}
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

```bash theme={null}
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 载荷：

```json theme={null}
{
  "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` 头部发送。

### 验证示例

<CodeGroup>
  ```typescript TypeScript theme={null}
  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");
  });
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

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

## 测试 Webhooks

向您的 Webhook 端点发送测试事件：

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
  -H "X-API-Key: awx_your_api_key"
```

## 查看投递记录

检查 Webhook 的投递历史：

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
  -H "X-API-Key: awx_your_api_key"
```

## 管理 Webhooks

```bash theme={null}
# List all webhooks
GET /webhooks

# Get a specific webhook
GET /webhooks/:id

# Update a webhook
PUT /webhooks/:id

# Delete a webhook
DELETE /webhooks/:id
```

## 最佳实践

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

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