Webhooks

Overview

Webhooks deliver real-time event notifications to your application via HTTP POST requests. Use them to react to payments, policy violations, agent status changes, and x402 session events.

Setting Up Webhooks

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

Via 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"
  }'

Event Types

Event	Description
`payment.completed`	Transaction confirmed on-chain
`payment.failed`	Transaction failed or reverted
`payment.pending`	Transaction submitted, awaiting confirmation
`agent.frozen`	Agent wallet was frozen
`agent.unfrozen`	Agent wallet was unfrozen
`policy.violated`	Transaction rejected by policy engine
`x402.session.expired`	x402 session budget or TTL exceeded
`approval.requested`	High-value transaction awaiting human approval

Webhook Payload

Every webhook delivery includes a JSON payload with this structure:

{
  "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"
  }
}

Signature Verification

Every webhook delivery includes a signature header for verification. Always verify signatures before processing webhook events.

How It Works

AgentWallex signs each webhook payload using the secret you provided at registration. The signature is sent in the X-AgentWallex-Signature header.

Verification Example

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)

Always use constant-time comparison (e.g., timingSafeEqual or hmac.compare_digest) when verifying signatures to prevent timing attacks.

Testing Webhooks

Send a test event to your webhook endpoint:

curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
  -H "X-API-Key: awx_your_api_key"

Viewing Deliveries

Check the delivery history for a webhook:

curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
  -H "X-API-Key: awx_your_api_key"

Managing Webhooks

# List all webhooks
GET /webhooks

# Get a specific webhook
GET /webhooks/:id

# Update a webhook
PUT /webhooks/:id

# Delete a webhook
DELETE /webhooks/:id

Best Practices

Respond to webhook deliveries with a 2xx status code within 5 seconds. If your handler needs to do heavy processing, acknowledge the webhook immediately and process asynchronously.

Always verify signatures before processing events.
Handle duplicates — Webhook deliveries may be retried. Use the id field for idempotency.
Return 200 quickly — Acknowledge receipt before doing heavy processing.
Monitor delivery failures — Check the deliveries endpoint for failed deliveries.
Use specific event filters — Subscribe only to the events you need rather than receiving all events.

Getting Started

Platform

Core Features

Guides

Overview

Setting Up Webhooks

Via SDK

Via API

Event Types

Webhook Payload

Signature Verification

How It Works

Verification Example

Testing Webhooks

Viewing Deliveries

Managing Webhooks

Best Practices

​Overview

​Setting Up Webhooks

​Via SDK

​Via API

​Event Types

​Webhook Payload

​Signature Verification

​How It Works

​Verification Example

​Testing Webhooks

​Viewing Deliveries

​Managing Webhooks

​Best Practices

Overview

Setting Up Webhooks

Via SDK

Via API

Event Types

Webhook Payload

Signature Verification

How It Works

Verification Example

Testing Webhooks

Viewing Deliveries

Managing Webhooks

Best Practices