Skip to main content
LearnGuidesHandle agent payments with webhooks
GUIDE

The webhook patterns developers ask about most.

15 minutes
SHORT ANSWER

A robust webhook handler does four things in order: HMAC-verify the signature against the raw body, dedupe by event id, enqueue the work to a background queue, and return 200. Long-running work happens in the worker, with retries and idempotency at the queue layer. payment.failed gets its own path that releases held resources and surfaces the failure to the user.

PREREQUISITES

Before you start.

  • A working agent profile and the signing secret from your dashboard (Settings - Webhooks).
  • A web framework with raw-body access - Express with express.raw, FastAPI, Flask, etc. Auto-parsing JSON middleware breaks signature verification.
  • A job queue: BullMQ (Node) or Celery/arq (Python). The webhook returns 200 fast and the queue does the slow work.
  • A database with an upsert primitive (Postgres works; Redis SET NX also works for short-lived dedupe).
  • A public HTTPS endpoint - in development, ngrok or a deploy preview. The sender will not deliver to private URLs.
STEP 1 OF 4

Verify the signature.

The signature is HMAC-SHA256 over the raw request body with the signing secret as key, hex-encoded, delivered in the X-Blockchain0x-Signature header. Verify with a constant-time compare to avoid timing-based attacks. If the bytes you sign locally do not match the bytes the sender signed, the comparison fails - which is why raw-body access matters.

TypeScript
import crypto from "node:crypto";
import express from "express";

const SIGNING_SECRET = process.env.BLOCKCHAIN0X_SIGNING_SECRET!;

export function verifyWebhook(req: express.Request): boolean {
  const sig = req.header("X-Blockchain0x-Signature") ?? "";
  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(req.body)        // req.body MUST be the raw bytes (no JSON parse).
    .digest("hex");
  try {
    return crypto.timingSafeEqual(
      Buffer.from(sig, "hex"),
      Buffer.from(expected, "hex"),
    );
  } catch {
    return false;            // length mismatch, non-hex, etc.
  }
}
Python
import hmac, hashlib, os
from flask import request

SIGNING_SECRET = os.environ["BLOCKCHAIN0X_SIGNING_SECRET"].encode()

def verify_webhook(raw_body: bytes) -> bool:
    sig = request.headers.get("X-Blockchain0x-Signature", "")
    expected = hmac.new(SIGNING_SECRET, raw_body, hashlib.sha256).hexdigest()
    # hmac.compare_digest handles length mismatches safely.
    return hmac.compare_digest(sig, expected)
STEP 2 OF 4

Make the handler idempotent.

Webhooks retry on any non-2xx response, and the same event will arrive multiple times under load even when nothing has gone wrong. Dedupe on the event's id using a database upsert. If the row already exists, skip; if it does not, insert and proceed. Postgres makes this a single statement.

TypeScript
// Pseudocode for a Postgres-backed dedupe table. Replace with your DB of choice.
async function processEventOnce(eventId: string, body: object) {
  // INSERT ... ON CONFLICT DO NOTHING returns rowCount === 0 on duplicate.
  const inserted = await db.query(
    "INSERT INTO webhook_events(id) VALUES ($1) ON CONFLICT DO NOTHING",
    [eventId],
  );
  if (inserted.rowCount === 0) return;          // Already processed.
  await handleEvent(body);
}
Python
async def process_event_once(event_id: str, body: dict):
    # INSERT ... ON CONFLICT DO NOTHING returns 0 rows on duplicate.
    inserted = await db.execute(
        "INSERT INTO webhook_events (id) VALUES ($1) ON CONFLICT DO NOTHING",
        event_id,
    )
    if inserted == "INSERT 0 0":   # asyncpg-style status
        return                     # Already processed.
    await handle_event(body)
STEP 3 OF 4

Enqueue and return 200 fast.

The webhook endpoint should respond within a second. Anything slower invites timeouts and retries. The pattern is: verify, enqueue, respond. The queue runs the actual delivery in a worker with retries, exponential backoff, and its own idempotency. BullMQ and Celery both support per-job ID, which prevents accidental re-enqueuing of the same event.

TypeScript (BullMQ)
// Express handler: verify, enqueue, return 200 fast.
import { Queue } from "bullmq";

const paymentQueue = new Queue("payments");

app.post(
  "/webhooks/payment",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verifyWebhook(req)) return res.status(401).send("Invalid signature");
    const event = JSON.parse(req.body.toString());
    await paymentQueue.add(event.type, event, {
      jobId: event.id,                  // Idempotency key.
      removeOnComplete: true,
      attempts: 5,
      backoff: { type: "exponential", delay: 1000 },
    });
    res.status(200).send("ok");
  },
);

// Worker file:
import { Worker } from "bullmq";
new Worker("payments", async (job) => {
  await handleEvent(job.data);
});
Python (Celery)
# Flask handler enqueues to Celery (or arq) and returns 200 quickly.
from celery import Celery
from flask import request

celery = Celery("payments", broker=os.environ["REDIS_URL"])

@celery.task(bind=True, max_retries=5)
def handle_payment_event(self, event):
    try:
        process_event_once(event["id"], event)
    except Exception as exc:
        raise self.retry(exc=exc, countdown=2 ** self.request.retries)

@app.post("/webhooks/payment")
def webhook():
    if not verify_webhook(request.get_data()):
        abort(401)
    event = request.get_json(force=True)
    handle_payment_event.apply_async(args=[event], task_id=event["id"])
    return "ok", 200

arq follows the same shape on the Python side - register the task with a deterministic job id and let the queue handle retries. The key constraint is that the enqueue itself must be fast (a single round trip to Redis); never block the webhook on remote calls.

STEP 4 OF 4

Handle payment.failed cleanly.

Every team wires up payment.confirmed and forgets payment.failed. When a payment request expires or the buyer abandons, the agent is left stuck in 'awaiting_payment'. Define the three things your handler must do on failure: release held resources, transition the agent's job to a terminal failure state, and (if appropriate) surface the outcome to the user.

TypeScript
function onPaymentFailed(event: PaymentFailedEvent) {
  // 1. Release any held resources tied to the payment request.
  releaseHeldResources(event.data.payment_request_id);

  // 2. Move the agent's job out of 'awaiting_payment' into 'failed'.
  markJobFailed(event.data.metadata.job_id, "payment_failed");

  // 3. (Optional) Notify the user, with a regenerate link.
  notifyUser(event.data.metadata.user_id, {
    template: "agent_payment_failed",
    request_id: event.data.payment_request_id,
  });
}
Python
def on_payment_failed(event):
    # 1. Release any held resources tied to the payment request.
    release_held_resources(event["data"]["payment_request_id"])

    # 2. Move the agent's job out of 'awaiting_payment' into 'failed'.
    mark_job_failed(event["data"]["metadata"]["job_id"], reason="payment_failed")

    # 3. (Optional) Notify the user with a regenerate link.
    notify_user(
        event["data"]["metadata"]["user_id"],
        template="agent_payment_failed",
        request_id=event["data"]["payment_request_id"],
    )
COMMON PITFALLS

Five mistakes that drop or duplicate events.

Parsing the body before verifying the signature

HMAC must be computed over the raw bytes the sender signed. If your framework auto-parses JSON before your handler runs, the bytes you sign locally will not match the bytes the sender signed (different whitespace, key order, encoding) and every signature will look invalid. Configure the route to receive the raw body (Express: express.raw, Flask: request.get_data), verify first, then parse.

Doing the actual work inside the webhook handler

Webhooks have aggressive retry policies. If your handler takes 30 seconds to deliver the work, the sender's timeout fires and the webhook gets resent - now you have two deliveries in flight for the same payment. Always: verify, enqueue, return 2xx. The actual work runs in a background worker that can take as long as it needs.

Using HTTP status to communicate business logic

If your handler returns a 4xx when the user no longer exists in your system, the sender treats that as 'invalid request' and stops retrying. If it returns 5xx for the same condition, the sender retries forever and your queue fills up. Return 200 once you have safely persisted the event (or recognized it as a dup); use queue logic, not HTTP status, to express business decisions.

Idempotency on a payload hash instead of the event ID

Two different events about the same payment (payment.received followed by payment.confirmed) have different bodies but legitimately need separate processing. If your dedupe is on a body hash you will accidentally drop the second event. Always dedupe on the event's id field (which is unique per event regardless of payment), and let the type field drive what your handler does.

Treating payment.received as the same as payment.confirmed

payment.received fires when the chain has seen the transaction; payment.confirmed fires after your platform's finality rules pass. A reorg between the two reverses the payment. Treat received as a soft hint (light up the UI, queue the work tentatively); treat confirmed as the trigger for irreversible delivery. Cheap, reversible work can use received; everything else must wait.

NEXT STEPS

Once webhooks are bulletproof.

Webhooks are the hard part. With the four patterns above in place, the remaining work is mostly operational: a test environment that exercises the failure paths, spend controls so an upstream agent does not flood your handler, and a final security review.

Test agent payments without real money

12 minutes

Set up agent spend controls that survive prompt injection

8 minutes

Secure your agent wallet before going live

15 minutes

Full reference at docs.blockchain0x.com. Webhook glossary: payment mandate. Product surface: Payment API.

Last reviewed: 2026-05-15. Published under CC BY 4.0.

Webhooks you can trust under load.

Signed, retried, idempotent. Free to start.