Webhooks

Agent Payments state changes are committed to a transactional outbox, then delivered through StableOps's signed Webhook pipeline. Delivery includes automatic retries, endpoint concurrency limits, manual replay, and dead-letter handling.

Configure an endpoint

Open Agent Payments Webhooks to create endpoints, rotate signing secrets, inspect delivery history, and replay failed or dead-letter deliveries.

Endpoints created here receive agent_payment.* events. Configure Sandbox and Live independently.

Two state axes

Each Agent payment tracks two independent kinds of state:

• payment_status: policy, approval, authorization, and onchain settlement state;
• resource_status: whether the paid HTTP request produced a reliable response.

Event types

settlement.unknown means the payment request may have reached the facilitator, but the available evidence cannot confirm the outcome. Query and reconcile the original Intent; never create a replacement Intent or authorization.

Payload shape

Regular payment events use a versioned envelope:

{
  "id": "7b91729e-41d0-4f9f-8dd1-6eea06a5764d",
  "type": "agent_payment.settlement.settled",
  "version": "1",
  "occurred_at": "2026-08-05T08:00:00.000Z",
  "data": {
    "organization_id": "org_...",
    "environment": "sandbox",
    "agent_id": "agent_...",
    "intent_id": "pint_...",
    "payment_status": "settled",
    "resource_status": "response_received",
    "amount_atomic": "1000",
    "asset": "USDC",
    "asset_contract": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "asset_decimals": 6,
    "network": "eip155:84532",
    "origin": "https://resource.example.com",
    "pay_to": "0x...",
    "approval_id": null,
    "authorization_id": "pauth_...",
    "receipt_id": "receipt_..."
  }
}

Pause events contain only the applicable organization, environment, Agent, or pause reason. Payloads never include Agent Keys, raw execution grants, complete payment signatures, private keys, or paid resource response bodies.

See the Agent Payments Webhook API reference for the complete versioned envelope, every event name, field types, required and nullable fields, and all three payload variants.

Safe handling rules

1. Verify the signature against the raw request body before parsing JSON.
2. Enforce uniqueness on the top-level id; retries and manual replay can redeliver an event.
3. Persist the event and return 2xx quickly. Move slow business work to your own queue.
4. Do not assume strict ordering across events. Before an irreversible action, query the current state with management.payments.get(intentId).
5. Alert and reconcile on settlement.unknown, settlement.reverted, or either pause event. Do not automatically repay.

See the general Webhook documentation for endpoint setup, raw-body verification, secret rotation, retry timing, and dead-letter replay.