웹훅은 HTTP POST 요청을 통해 애플리케이션에 실시간 이벤트 알림을 전달합니다. 결제, 정책 위반, 에이전트 상태 변경, x402 세션 이벤트에 대응하기 위해 사용합니다.
웹훅 설정
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 | 사람 승인을 기다리는 고액 거래 |
웹훅 페이로드
모든 웹훅 전달에는 다음 구조의 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"
}
}
서명 검증
모든 웹훅 전달에는 검증을 위한 서명 헤더가 포함됩니다. 웹훅 이벤트를 처리하기 전에 항상 서명을 검증하세요.
작동 방식
AgentWallex는 등록 시 제공한 시크릿을 사용하여 각 웹훅 페이로드에 서명합니다. 서명은 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)를 사용하세요.
웹훅 테스트
웹훅 엔드포인트에 테스트 이벤트를 전송합니다:
curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
-H "X-API-Key: awx_your_api_key"
전달 내역 조회
웹훅의 전달 내역을 확인합니다:
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
-H "X-API-Key: awx_your_api_key"
웹훅 관리
# 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 상태 코드로 웹훅 전달에 응답하세요. 핸들러가 무거운 처리를 수행해야 하는 경우 웹훅을 즉시 승인하고 비동기적으로 처리하세요.
- 항상 서명을 검증하세요 — 이벤트를 처리하기 전에 검증하세요.
- 중복 처리 — 웹훅 전달은 재시도될 수 있습니다. 멱등성을 위해
id 필드를 사용하세요.
- 빠르게 200을 반환하세요 — 무거운 처리를 수행하기 전에 수신을 확인하세요.
- 전달 실패 모니터링 — 실패한 전달을 위해 전달 엔드포인트를 확인하세요.
- 특정 이벤트 필터 사용 — 모든 이벤트를 수신하지 말고 필요한 이벤트만 구독하세요.
