웹훅 - AgentWallex

개요

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

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)를 사용하세요.

웹훅 테스트

웹훅 엔드포인트에 테스트 이벤트를 전송합니다:

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을 반환하세요 — 무거운 처리를 수행하기 전에 수신을 확인하세요.
전달 실패 모니터링 — 실패한 전달을 위해 전달 엔드포인트를 확인하세요.
특정 이벤트 필터 사용 — 모든 이벤트를 수신하지 말고 필요한 이벤트만 구독하세요.

시작하기

플랫폼

핵심 기능

가이드

웹훅

개요

웹훅 설정

SDK를 통한 설정

API를 통한 설정

이벤트 유형

웹훅 페이로드

서명 검증

작동 방식

검증 예시

웹훅 테스트

전달 내역 조회

웹훅 관리

모범 사례

​개요

​웹훅 설정

​SDK를 통한 설정

​API를 통한 설정

​이벤트 유형

​웹훅 페이로드

​서명 검증

​작동 방식

​검증 예시

​웹훅 테스트

​전달 내역 조회

​웹훅 관리

​모범 사례

개요

웹훅 설정

SDK를 통한 설정

API를 통한 설정

이벤트 유형

웹훅 페이로드

서명 검증

작동 방식

검증 예시

웹훅 테스트

전달 내역 조회

웹훅 관리

모범 사례