Webhook

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

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)

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.

Bắt đầu

Nền tảng

Tính năng cốt lõi

Hướng dẫn

Tổng quan

Thiết lập Webhook

Qua SDK

Qua API

Các Loại Sự kiện

Payload Webhook

Xác minh Chữ ký

Cách hoạt động

Ví dụ Xác minh

Kiểm tra Webhook

Xem lịch sử Giao hàng

Quản lý Webhook

Các phương pháp tốt nhất

​Tổng quan

​Thiết lập Webhook

​Qua SDK

​Qua API

​Các Loại Sự kiện

​Payload Webhook

​Xác minh Chữ ký

​Cách hoạt động

​Ví dụ Xác minh

​Kiểm tra Webhook

​Xem lịch sử Giao hàng

​Quản lý Webhook

​Các phương pháp tốt nhất

Tổng quan

Thiết lập Webhook

Qua SDK

Qua API

Các Loại Sự kiện

Payload Webhook

Xác minh Chữ ký

Cách hoạt động

Ví dụ Xác minh

Kiểm tra Webhook

Xem lịch sử Giao hàng

Quản lý Webhook

Các phương pháp tốt nhất