Home › Docs › Webhooks & Callbacks

Webhooks & Callbacks

How to handle async workflows, retries, and long-running tool chains with Agent402.

Current async patterns

All Agent402 tools return results synchronously in the HTTP response. For workflows that chain multiple tools, here are the patterns available today:

Idempotent retries Available

Add an Idempotency-Key header to any request. If a network error occurs mid-flight, retry safely - the server returns the cached result without re-charging.

Sequential chaining Available

Chain tools by calling them in sequence, for example render → extract → memory-write (wallet-only tools, paid per call). Each call is independent and stateless. Use workflow examples for patterns.

Wallet-keyed state Available

Use the memory tools (memory-write, memory-read) to persist intermediate results across tool calls. Your wallet address is your identity - no accounts needed.

Idempotent retries in practice

Pass an Idempotency-Key header with any unique string. The server caches the result keyed to your request + credential combination:

curl -X POST https://agent402.tools/api/hash \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"text":"hello","algo":"sha256"}'

# Retry the same request - returns cached result, no re-charge
curl -X POST https://agent402.tools/api/hash \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{"text":"hello","algo":"sha256"}'

The cache key is sha256(METHOD /path + key + credential), so different callers with the same idempotency key don't collide.

Chaining with agent402-client

import { Agent402 } from "agent402-client";

// Free tier: each call settles its own proof-of-work, no wallet needed
const a = new Agent402();
const md = await a.call("html-to-markdown", { html: "<h1>Q3 report</h1><p>Revenue rose.</p>" });
const stats = await a.call("text-stats", { text: md.markdown });

// Wallet-only tools chain the same way through a payment-wrapped fetch.
// Memory is keyed to the wallet that signs the x402 payment.
// payFetch: an @x402/fetch-wrapped fetch (see the USDC tab on /quickstart).
const paid = new Agent402({ fetch: payFetch });
const page = await paid.call("extract", { url: "https://example.com" });
await paid.call("memory-write", { key: "example-title", value: page.title });

Planned: webhook callbacks Planned

We're designing a webhook system for long-running chains. The planned flow:

How it will work

1. Submit a tool call with a X-Callback-URL header pointing to your endpoint.
2. Agent402 returns 202 Accepted with a job ID immediately.
3. When the tool completes, Agent402 POSTs the result to your callback URL with an HMAC signature for verification.
4. Poll /api/jobs/:id as a fallback if the callback fails.

Want to be notified when webhooks launch? Follow @Agent402Tools or watch the GitHub repo.

Workflow examples - see how tools chain together
Quickstart - get your first call working in 60 seconds
Documentation - full API reference