Tổng quan
Webhook cung cấp thông báo sự kiện thời gian thực đến ứng dụng của bạn qua các yêu cầu HTTP POST. Sử dụng chúng để phản ứng với thanh toán, vi phạm chính sách, thay đổi trạng thái tác nhân và sự kiện phiên x402.
Thiết lập Webhook
Qua 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",
});
Qua 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"
}'
Các Loại Sự kiện
| Sự kiện | Mô tả |
|---|
payment.completed | Giao dịch đã được xác nhận on-chain |
payment.failed | Giao dịch thất bại hoặc bị hoàn ngược |
payment.pending | Giao dịch đã gửi, đang chờ xác nhận |
agent.frozen | Ví tác nhân đã bị đóng băng |
agent.unfrozen | Ví tác nhân đã được mở đóng băng |
policy.violated | Giao dịch bị từ chối bởi công cụ chính sách |
x402.session.expired | Ngân sách hoặc TTL phiên x402 đã hết |
approval.requested | Giao dịch giá trị cao đang chờ phê duyệt con người |
Payload Webhook
Mỗi lần gửi webhook bao gồm payload JSON với cấu trúc sau:
{
"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"
}
}
Xác minh Chữ ký
Mỗi lần gửi webhook đều bao gồm header chữ ký để xác minh. Luôn xác minh chữ ký trước khi xử lý sự kiện webhook.
Cách hoạt động
AgentWallex ký mỗi payload webhook bằng bí mật bạn cung cấp khi đăng ký. Chữ ký được gửi trong header X-AgentWallex-Signature.
Ví dụ Xác minh
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");
});
Luôn sử dụng so sánh thời gian không đổi (ví dụ: timingSafeEqual hoặc hmac.compare_digest) khi xác minh chữ ký để ngăn chặn tấn công thời gian.
Kiểm tra Webhook
Gửi sự kiện thử nghiệm đến endpoint webhook của bạn:
curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
-H "X-API-Key: awx_your_api_key"
Xem lịch sử Giao hàng
Kiểm tra lịch sử giao hàng cho webhook:
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
-H "X-API-Key: awx_your_api_key"
Quản lý 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
Các phương pháp tốt nhất
Phản hồi giao hàng webhook với mã trạng thái 2xx trong vòng 5 giây. Nếu trình xử lý cần thực hiện xử lý nặng, hãy xác nhận webhook ngay lập tức và xử lý bất đồng bộ.
- Luôn xác minh chữ ký trước khi xử lý sự kiện.
- Xử lý trùng lặp — Giao hàng webhook có thể được thử lại. Sử dụng trường
id cho tính idempotent.
- Trả về 200 nhanh chóng — Xác nhận nhận trước khi thực hiện xử lý nặng.
- Giám sát lỗi giao hàng — Kiểm tra endpoint giao hàng cho các giao hàng thất bại.
- Sử dụng bộ lọc sự kiện cụ thể — Chỉ đăng ký các sự kiện bạn cần thay vì nhận tất cả sự kiện.
