Events

AgentaOS sends webhook events for checkouts, outbound sends, and subscriptions. Every event shares the same envelope, an id, a type, and a data object whose shape depends on the type. See Webhooks for how to register a URL and verify the signature before trusting any of this.

Every amount field below is a string (e.g. "49.99"), not a number. This differs from amount on SDK create calls (checkouts, payment links), which is a plain number in currency units. Parse it before doing arithmetic.

The field names below are the literal snake_case keys AgentaOS POSTs to your webhookUrl, what you parse in any language. As returned by the SDK webhooks.verify() (Node.js) the same fields come back camelCased and typed: link_id becomes linkId, session_id becomes sessionId, tx_hash becomes txHash, payer_type becomes payerType, chain_id becomes chainId, transaction_id becomes transactionId, and so on. This page mirrors the raw body documented in Webhooks.

string

Unique event ID, e.g. evt_550e8400-e29b-41d4-a716-446655440000. Always present. For checkout.session.completed it is independent of data.session_id. For send.completed and send.failed it is derived as evt_${data.transaction_id}, so a redelivered send always carries the same event id. Either way, use id to deduplicate the delivery, and the data-level ID (session_id or transaction_id) to deduplicate the underlying payment or send.

string

One of checkout.session.completed, send.completed, send.failed, or a subscription.* event. Switch on this to decide how to parse data.

object

Event-specific payload. See each event below.

`checkout.session.completed`

Fired when a checkout is paid, by card, wallet, or stablecoin. This is the event to listen for to fulfill an order.

Hide data fields

string | null

The payment link’s secure_link_id. null for a standalone checkout created without a link.

string

The checkout’s public session ID. The stable identifier to key your fulfillment and idempotency logic off.

string

Amount paid, in currency units, as a string. e.g. "49.99".

string

Settlement currency, e.g. "EUR".

string

How the buyer actually paid: card, sepa, bank_transfer, bridge, or wallet.

string | null

On-chain transaction hash for stablecoin checkouts. null for card/bank rails, use vendor_reference instead.

string | null

Off-chain audit reference (card-processor payment reference, bank reference). null for on-chain rails.

string | null

The paying wallet address for stablecoin checkouts. null for card/bank rails.

string

human or agent, whether a person or an autonomous agent initiated the payment.

string

CAIP-2 network ID for on-chain rails, e.g. "eip155:8453" for Base, or stripe for card/bank.

boolean

true in live mode, false in test mode.

number | null

Set when a bank-transfer buyer sent more than the amount due (beyond a 1-cent tolerance). null otherwise.

object

The custom key-value data you attached when creating the checkout or payment link.

tx_hash, payer, and network describe on-chain settlement. For checkouts paid by card, these fields are empty, use vendor_reference for the off-chain reference and don’t assume the on-chain fields are always populated. Key fulfillment off session_id and amount/currency, which are present for every payment method.

Example

{
  "id": "evt_8c7d6e5f-4a3b-2c1d-0e9f-8a7b6c5d4e3f",
  "type": "checkout.session.completed",
  "data": {
    "link_id": "mZrESFyR7RC9RPsJfZCVkg",
    "session_id": "kR9pQwErTyUiOpAsDfGh",
    "amount": "49.99",
    "currency": "EUR",
    "rail": "card",
    "tx_hash": null,
    "vendor_reference": "pi_3P...",
    "payer": null,
    "payer_type": "human",
    "network": "stripe",
    "livemode": true,
    "overpaid_by_cents": null,
    "metadata": { "orderId": "order-123" }
  }
}

`send.completed`

Fired when an outbound stablecoin send you initiated confirms on-chain.

Hide data fields

string

Internal transaction ID. Use this to deduplicate retried deliveries.

string

On-chain transaction hash of the confirmed send.

string

Sending wallet address (your organization’s wallet).

string

Recipient wallet address.

string

Amount sent, in token units, as a string. e.g. "49.99".

string

Token symbol, e.g. "USDC".

number

EVM chain ID, e.g. 8453 for Base.

string

CAIP-2 network ID, e.g. "eip155:8453".

boolean

true in live mode, false in test mode.

string | null

Optional description you attached to the send. null if none was set.

Example

{
  "id": "evt_9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
  "type": "send.completed",
  "data": {
    "transaction_id": "9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
    "tx_hash": "0xabc123...",
    "from": "0xorgwallet...",
    "to": "0xrecipient...",
    "amount": "100.00",
    "token": "USDC",
    "chain_id": 8453,
    "network": "eip155:8453",
    "livemode": true,
    "description": "Payout to contractor"
  }
}

`send.failed`

Fired when an outbound send fails to broadcast, network error, insufficient balance, or the transaction reverted.

Hide data fields

string

Internal transaction ID. Use this to deduplicate retried deliveries.

null

Always null, the send never confirmed on-chain.

string

Sending wallet address (your organization’s wallet).

string

Intended recipient wallet address.

string

Amount that was attempted, in token units, as a string.

string

Token symbol, e.g. "USDC".

number

EVM chain ID, e.g. 8453 for Base.

string

CAIP-2 network ID, e.g. "eip155:8453".

boolean

true in live mode, false in test mode.

string | null

Optional description you attached to the send. null if none was set.

Example

{
  "id": "evt_8fae0d2b-7d54-4b3e-9a41-2b3f9c1e0aa2",
  "type": "send.failed",
  "data": {
    "transaction_id": "8fae0d2b-7d54-4b3e-9a41-2b3f9c1e0aa2",
    "tx_hash": null,
    "from": "0xorgwallet...",
    "to": "0xrecipient...",
    "amount": "100.00",
    "token": "USDC",
    "chain_id": 8453,
    "network": "eip155:8453",
    "livemode": true,
    "description": null
  }
}

send.failed means the transaction never landed on-chain. It’s distinct from a payment dispute or a card decline, those don’t go through this event, they affect your balance directly. See Payouts.

Subscription events

Subscription lifecycle events, delivered to your organization webhook endpoint. All five share the same data shape.

subscription.created first payment succeeded; now active (or trialing).
subscription.renewed a cycle was paid and renewed for another period.
subscription.payment_failed a renewal payment failed; now past due.
subscription.updated the subscription changed: a cancel scheduled or resumed (cancel_at_period_end), a downgrade scheduled (pending_plan set), a scheduled downgrade reverted (pending_plan null again), an upgrade applied (new plan_name / link_id / amount_minor), or the scheduled plan taking over at the period end.
subscription.canceled terminal; no further charges.

Hide data fields

string

The subscription ID.

string

Stripe status: active, trialing, past_due, unpaid, canceled, incomplete.

string | null

Plan name, from the backing payment link.

string

e.g. "EUR".

number

Per-cycle price in integer minor units. 1000 = €10.00.

string | null

ISO 8601, or null before the first cycle.

boolean

true if cancellation is scheduled for period end.

string

The current plan’s payment-link id (the linkId you pass to checkouts.create).

object | null

Null unless a downgrade is scheduled. Then { link_id, plan_name, amount_minor, effective_at }: the plan the subscription switches to at effective_at (the period end). plan_name, link_id and amount_minor above stay what the buyer paid for until then.

string | null

boolean

true in live mode, false in test mode.

Example

{
  "id": "evt_3f2a1b0c-9d8e-7f6a-5b4c-3d2e1f0a9b8c",
  "type": "subscription.renewed",
  "data": {
    "id": "sub_6pC2lNB6joCRQIZ1aMrTpi",
    "status": "active",
    "plan_name": "Pro Monthly",
    "currency": "EUR",
    "amount_minor": 1000,
    "current_period_end": "2026-09-19T12:00:00.000Z",
    "cancel_at_period_end": false,
    "customer_email": "customer@example.com",
    "customer_name": "Alex Rivera",
    "livemode": true
  }
}

Next steps

Verify signatures

How to register a URL and verify the HMAC-SHA256 signature, in TypeScript, Python, Go, and PHP.

Payment SDK: Webhooks

The webhooks resource in @agentaos/pay.

Getting Started

Build with AI agents

Sell

Merchant of Record

Webhooks

For customers

Experimental

`checkout.session.completed`

`send.completed`

`send.failed`

Subscription events

Next steps

Verify signatures

Payment SDK: Webhooks

​checkout.session.completed

​send.completed

​send.failed

​Subscription events

​Next steps

Verify signatures

Payment SDK: Webhooks

`checkout.session.completed`

`send.completed`

`send.failed`

Subscription events

Next steps