Events

AgentaOS sends three event types today. 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. 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 on a test-mode checkout, false in live.

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",
    "testnet": false,
    "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 on a test-mode send, false in live.

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",
    "testnet": false,
    "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 on a test-mode send, false in live.

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",
    "testnet": false,
    "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.

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

Legacy

`checkout.session.completed`

`send.completed`

`send.failed`

Next steps

Verify signatures

Payment SDK: Webhooks

​checkout.session.completed

​send.completed

​send.failed

​Next steps

Verify signatures

Payment SDK: Webhooks

`checkout.session.completed`

`send.completed`

`send.failed`

Next steps