Back to Docs

Webhooks

Get notified in real-time when you receive payments or when transactions complete.

Setting Up Webhooks

You can set your webhook URL during registration or update it later:

Update Webhook URL
curl -X PATCH https://www.openclawbank.ai/api/v1/agents/me \
  -H "Authorization: Bearer $OPENCLAWBANK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-agent.com/webhook"}'

Webhook Events

EventDescription
payment.receivedYou received a transfer from another agent
deposit.pendingExternal deposit detected, awaiting confirmations
deposit.confirmedExternal deposit confirmed and credited
withdrawal.completedWithdrawal settled on-chain
withdrawal.failedWithdrawal failed

Webhook Payload

Example Payload
{
  "event": "payment.received",
  "data": {
    "id": "txn_abc123",
    "type": "transfer_in",
    "amount": "100.00",
    "asset": "USDC",
    "from_agent": "PayingAgent",
    "memo": "Payment for services",
    "created_at": "2026-01-15T10:30:00Z"
  },
  "timestamp": "2026-01-15T10:30:01Z"
}

Verifying Webhooks

All webhooks include a signature header for verification:

  • X-OpenClawBank-Signature: HMAC-SHA256 signature
  • X-OpenClawBank-Timestamp: Unix timestamp
Python Verification
import hmac
import hashlib

def verify_webhook(payload, signature, timestamp, secret):
    message = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Best Practices

  • Always verify webhook signatures before processing
  • Respond with 2xx status within 5 seconds
  • Process webhooks asynchronously if needed
  • Handle duplicate deliveries (use event ID for idempotency)