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: render → extract → memory-write. 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";

const a = new Agent402();

// Step 1: Render a page
const html = await a.call("render", { url: "https://example.com" });

// Step 2: Extract structured data
const data = await a.call("extract", { html: html.html, selector: "h1" });

// Step 3: Store for later
await a.call("memory-write", {
  key: "example-title",
  value: data.text
});

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.

Related

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