Events

AgentaOS sends 12 webhook event types, for checkouts, outbound sends, subscriptions, disputes, account verification, and the dashboard’s test event. This page is the full list. Every event shares the same envelope: an id, a type, a business, and a data object whose shape depends on the type. See Webhooks for how to register a URL and verify the signature before you trust any of this. Amounts follow the money model: amount is a string in currency units, and amount_minor is an integer in the smallest currency unit.

The field names below are the literal snake_case keys AgentaOS POSTs to your webhookUrl: parse these in any language. The SDK’s webhooks.verify() (Node.js) returns the same fields camelCased: link_id becomes linkId, session_id becomes sessionId, trial_end becomes trialEnd, and so on.

When each event fires

Each event type below lists every trigger in the platform. Which action fires which event gives the same facts in the other direction, per action.

Event	Fires when	What to do
`checkout.session.completed`	A buyer pays a checkout by card, bank transfer or stablecoin. A free trial starts: `amount` is `"0"` and `trial` is `true`. A trial with a trial price starts: `amount` is the amount charged. A later subscription charge succeeds: a renewal, the first charge after a trial, or an upgrade’s prorated charge. A subscriber credit pays a renewal in full: `amount` is `"0"`.	Fulfill the order or unlock access.
`checkout.session.bank_transfer_pending`	A buyer chooses bank transfer on a checkout and receives the bank details. Sent once per checkout. `amount` is the total to pay, VAT included, in the same form as `checkout.session.completed`.	Hold the order until `checkout.session.completed`, or cancel the checkout if you cannot wait.
`subscription.created`	The subscription becomes `active` or `trialing` for the first time: the buyer pays the first period, or saves a card for a trial.	Store the subscription `id` with your user.
`subscription.renewed`	A charge after the first one succeeds: a renewal, the first charge after a trial, or an upgrade’s prorated charge. A renewal that a subscriber credit pays also fires it.	Extend access to `current_period_end`.
`subscription.payment_failed`	The status becomes `past_due` or `unpaid`: a renewal charge fails, including the first charge after a trial.	Ask the subscriber to update their card.
`subscription.updated`	A cancel is scheduled. A scheduled cancel is resumed. An upgrade is applied. A downgrade is scheduled. A scheduled downgrade is reverted. A scheduled downgrade takes over at the period end.	Store the payload as the subscription’s latest state.
`subscription.canceled`	The status becomes `canceled`: at the period end after a scheduled cancel, or when the card processor ends the subscription for another reason.	Remove access.
`dispute.created`	AgentaOS finds a new dispute on one of your sales.	Mark the order as disputed and reply to our dispute email with your evidence; AgentaOS answers the buyer’s bank.
`dispute.closed`	A dispute closes in your favor, or a bank inquiry closes without a chargeback. A lost dispute sends no event.	Clear the disputed mark on the order.
`send.completed`	An outbound stablecoin send that you started is confirmed.	Mark the payout as paid.
`send.failed`	An outbound stablecoin send that you started fails: the broadcast fails, for example on a network error or an insufficient balance, or the transaction reverts on-chain.	Retry the send.
`account.updated`	A business’s verification changes, in live mode only. Its identity check is verified or declined. Our reviewers approve, reject, hold or resume the business, or ask for a change. Our reviewers verify or withdraw its identity by hand. The event goes to the business and to the platform that manages it.	Show the business its next step from `verification`.
`webhook.test`	You click Send test event in Settings → Developers → Webhooks.	Check that your endpoint verifies it.

Event envelope

string

The event ID. A paid checkout’s id is evt_ plus the sale’s transaction id, a send’s id is evt_ plus data.transaction_id, and every other event gets a random id such as evt_4e1b9a0c2d3f5a67. An event keeps its id across delivery attempts and a retry from the dashboard. The SDK’s WebhookEvent type does not declare id yet, so deduplicate on the keys in Deduplication.

string

One of checkout.session.completed, checkout.session.bank_transfer_pending, send.completed, send.failed, subscription.created, subscription.renewed, subscription.payment_failed, subscription.updated, subscription.canceled, dispute.created, dispute.closed, account.updated, or webhook.test. Switch on this to decide how to parse data.

string

The id of the business the event happened in. On your own events it is your own id. If you are a platform, your webhook also receives the events of every business you manage, and there business is your client’s id. See Platform webhooks.

object

Event-specific payload. See each event below.

Which action fires which event

Events describe money and account state, not every API call. An action that changes nothing about a payment, a subscription or a business’s verification sends no event. A “check” below is AgentaOS reading the current state from the card processor. While the buyer’s checkout page is open, AgentaOS checks within seconds. A background check runs every 5 minutes for subscriptions and every 10 minutes for disputes.

Your API calls

Action	Event	When
Create a payment link	None
Update a payment link	None
Cancel a payment link	None
Create a checkout	None	The buyer’s payment sends `checkout.session.completed` later.
Cancel a checkout	None, unless the buyer already paid: then `checkout.session.completed`
Cancel a subscription	`subscription.updated`	Right away, when the call schedules the cancel. A repeat call sends nothing. `subscription.canceled` follows when the period ends.
Resume a subscription	`subscription.updated`	Right away.
Change the plan	`subscription.updated`	Right away, for an upgrade, a scheduled downgrade, and the undo of a scheduled downgrade.
Preview a plan change	None	The preview changes nothing.
Give a subscriber credit	None	A renewal that the credit pays sends the usual renewal events.
Create a discount code	None
Stop a discount code	None
Void an invoice	None
Re-send the receipt email	None
Create a business	None	`account.updated` fires later, when the business’s verification changes.
Resend the invitation	None
Revoke the invitation	None
Create a verification link	None	`account.updated` fires when your client completes the identity check.
Send test event in Settings → Developers → Webhooks	`webhook.test`	Right away.

Actions outside your API calls

Action	Event	When
A buyer pays a checkout, by card, bank transfer or stablecoin	`checkout.session.completed`	When AgentaOS confirms the payment.
A buyer chooses bank transfer on a checkout	`checkout.session.bank_transfer_pending`	Right away.
A buyer subscribes and pays the first period	`subscription.created` and `checkout.session.completed`	On the next check.
A buyer starts a free trial	`subscription.created` and `checkout.session.completed` with `amount: "0"`	On the next check after the card is saved.
A renewal charge succeeds, including the first charge after a trial	`checkout.session.completed` and `subscription.renewed`	On the next check after the charge.
An upgrade’s prorated charge succeeds	`checkout.session.completed` and `subscription.renewed`	On the next check after the charge.
A renewal charge fails, including the first charge after a trial	`subscription.payment_failed`, once. Later failed retries of the same charge send nothing more.	On the next check.
A failed renewal charge succeeds on a later retry	`checkout.session.completed` and `subscription.renewed`, the same as any renewal	On the next check after the charge.
A scheduled cancel takes effect at the period end	`subscription.canceled`	On the next check after the period ends.
A scheduled downgrade takes over at the period end	`subscription.updated`	On the next check after the period ends.
A buyer’s bank opens a chargeback	`dispute.created`	On the next dispute check.
A chargeback closes in your favor	`dispute.closed`	On the next dispute check.
A bank inquiry closes without a chargeback	`dispute.closed` with `status: "warning_closed"`	On the next dispute check.
A chargeback closes against you	None
A business’s identity check is verified or declined	`account.updated`	When AgentaOS reads the result.
Our reviewers approve, reject, hold or resume a business, or ask for a change	`account.updated`	Right away.
A stablecoin send you started confirms on-chain	`send.completed`	When the transaction confirms.
A stablecoin send you started fails	`send.failed`	When the send fails.

For the order of the subscription events, see Event order for subscriptions.

Which URL receives an event

A checkout.session.completed event goes to one URL: the checkout’s own webhookUrl if it has one, else its payment link’s, else your account’s webhook URL. The first one found is the only one that receives it. Every other event goes to your account’s webhook URL. If no URL applies, AgentaOS sends nothing and shows no error.

Delivery and retries

AgentaOS sends each event as a POST with Content-Type: application/json and an X-AgentaOS-Signature header. A delivery follows these rules:

Each attempt times out after 10 seconds. A response outside 2xx, a timeout, or a network error counts as a failed attempt.
AgentaOS makes up to 3 attempts. It waits 1 second before the second attempt and 2 seconds before the third.
The 3 attempts carry the same signature, with the same t.
AgentaOS does not follow redirects. A 3xx response is a failed attempt.
AgentaOS refuses a URL that resolves to a private or internal address, such as localhost, 10.0.0.0/8 or 192.168.0.0/16, and marks the event failed without an attempt. For local development, expose your server through a public HTTPS tunnel.

After the third failed attempt, AgentaOS marks the event failed in Settings → Developers → Webhooks and sends it no more by itself. An owner or admin can send a failed event again with the retry button on its row (labeled “Retry webhook”). The retry sends the same body, signed again with a new t. Events are delivered independently of each other. Two events about the same subscription can arrive in either order.

Deduplication

The same event can arrive more than once: after a retry, or when your server stored the event but answered too slowly. Record a key per event and skip one you have already handled.

Event	Key
`checkout.session.completed`	`data.session_id`
`send.completed`, `send.failed`	`data.transaction_id`
`subscription.created`, `subscription.renewed`, `subscription.payment_failed`, `subscription.canceled`	The event `type`, `data.id` and `data.current_period_end`
`subscription.updated`	None. Two updates in the same period, such as a cancel scheduled and then resumed, share the same `type`, `data.id` and `data.current_period_end`. Apply the event as the subscription’s latest state instead of skipping it.
`dispute.created`, `dispute.closed`	The event `type` and `data.dispute_id`

Event order for subscriptions

AgentaOS checks each subscription with the card processor on a schedule and sends the events for what changed. The events below are what your endpoint receives. Unlock access on checkout.session.completed: it carries the metadata of the checkout, with your own ids.

What happens	Events
A buyer subscribes and pays the first period	`subscription.created` and `checkout.session.completed`, in either order
A buyer starts a free trial	`subscription.created` with `status: "trialing"`, and `checkout.session.completed` with `amount: "0"` and `trial: true`
A buyer starts a trial with a trial price	`subscription.created`, and `checkout.session.completed` with the amount charged for the trial. There is no `trial` field.
The trial ends and the first full charge succeeds	`checkout.session.completed` and `subscription.renewed`
A later period is paid	`checkout.session.completed` and `subscription.renewed`
A renewal charge fails	`subscription.payment_failed`, once, however many retries fail
A failed renewal charge succeeds on a later retry	`checkout.session.completed` and `subscription.renewed`, with nothing that marks it as a retry
A cancel is scheduled or resumed, or a plan changes	`subscription.updated`
The subscription ends	`subscription.canceled`

The checkout.session.completed for a renewal, or for the first charge after a trial, has its own session_id. Its metadata is AgentaOS’s own, not the metadata you set on the checkout, so your metadata.customerId is not on it. Match it to your user through metadata.subscriptionId, the subscription’s id, which is also on the first checkout event. The metadata of a renewal, and of the first charge after a trial, also has subscriptionCycle: true.

`checkout.session.completed`

Fires when:

A buyer pays a checkout by card, bank transfer or stablecoin.
A free trial starts: amount is "0" and trial is true.
A trial with a trial price starts: amount is the amount charged.
A later subscription charge succeeds: a renewal, the first charge after a trial, or an upgrade’s prorated charge.
A subscriber credit pays a renewal in full: amount is "0".

This is the event to listen for to fulfill an order. For the order of subscription events, see Event order for subscriptions.

Hide data fields

string | null

The payment link’s public token: the last part of its checkoutUrl (https://app.agentaos.ai/pay/<token>). It is not the link’s id, which checkouts.create({ linkId }) and the subscription events use. null for a checkout created without a link.

string

The checkout’s public session ID. Key your fulfillment and deduplication on it.

string

Amount paid, in currency units, as a string, e.g. "49.99". "0" for a free trial start.

string

The currency the buyer was charged in: the fiat currency, e.g. "EUR" or "USD", for a card or bank checkout, and the token, e.g. "USDC", for a wallet checkout.

string

How the buyer paid: card, sepa (a bank transfer), or crypto.

string | null

On-chain transaction hash for a stablecoin payment. null for a card or bank sale: use vendor_reference there.

string | null

The payment’s reference at the card processor or the bank. null for a stablecoin payment.

string | null

The paying wallet address for a stablecoin payment. null for a card or bank sale.

string

human or agent: whether a person or an autonomous agent made the payment.

string | null

AgentaOS’s own id for the buyer, the id the Customers API returns. It is not your user id: put your own id in metadata, for example metadata.customerId.

string | null

The buyer’s email, when the checkout collected one.

string | null

The buyer’s name, when the checkout collected one.

string

card for a card payment, bank_transfer for a bank transfer, or a CAIP-2 network ID such as "eip155:8453" (Base) for a stablecoin payment.

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.

boolean

Present only when the checkout started a free trial, and then always true. metadata.trial is also true on that event.

string | null

Present only with trial: the ISO 8601 time the trial ends and the first charge is due.

object

The key-value data you attached when you created the checkout or payment link. On a renewal it is AgentaOS’s own: see Event order for subscriptions.

The SDK’s CheckoutCompletedData type differs from the wire body in two ways. It types txHash, payer and linkId as string, but they are null in the cases above, so check for null. It does not declare rail, vendorReference, customerId, buyerEmail, buyerName, overpaidByCents, trial or trialEnd yet, although verify() returns them: read them with a cast, as shown in Payment SDK: Webhooks.

Example

{
  "id": "evt_8c7d6e5f-4a3b-2c1d-0e9f-8a7b6c5d4e3f",
  "type": "checkout.session.completed",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "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",
    "customer_id": "3c9d2e1f-7a6b-4c5d-8e9f-0a1b2c3d4e5f",
    "buyer_email": "customer@example.com",
    "buyer_name": "Alex Rivera",
    "network": "card",
    "livemode": true,
    "overpaid_by_cents": null,
    "metadata": { "orderId": "order-123" }
  }
}

`send.completed`

Fires when: an outbound stablecoin send that you started is confirmed.

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",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "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`

Fires when: an outbound stablecoin send that you started fails: the broadcast fails, for example on a network error or an insufficient balance, or the transaction reverts on-chain.

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",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "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. A payment dispute or a card decline does not fire this event: those affect your balance directly. See Payouts.

Subscription events

Fires when:

subscription.created: the subscription becomes active or trialing for the first time: the buyer pays the first period, or saves a card for a trial.
subscription.renewed: a charge after the first one succeeds: a renewal, the first charge after a trial, or an upgrade’s prorated charge. A renewal that a subscriber credit pays also fires it. The first period does not fire it.
subscription.payment_failed: the status becomes past_due or unpaid: a renewal charge fails, including the first charge after a trial. It fires once when the status first moves there; a move from past_due to unpaid, and every later failed retry, sends nothing more.
subscription.updated: a cancel is scheduled or resumed (cancel_at_period_end), an upgrade is applied (new plan_name, link_id and amount_minor), a downgrade is scheduled (pending_plan set), a scheduled downgrade is reverted (pending_plan null again), or a scheduled downgrade takes over at the period end.
subscription.canceled: the status becomes canceled: at the period end after a scheduled cancel, or when the card processor ends the subscription for another reason. No more charges follow.

Subscription lifecycle events, delivered to your account’s webhook URL. All five share the same data shape. For the order they arrive in, see Event order for subscriptions.

Hide data fields

string

The subscription’s id, a UUID. The same value as metadata.subscriptionId on the checkout event and id in the subscriptions API.

string

The status after the change, one of the eight subscription statuses. A subscription that never activated sends no event, so incomplete and incomplete_expired do not appear on events.

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, a UUID: the linkId you pass to checkouts.create. It is not the token in the checkout URL that checkout.session.completed sends as link_id.

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.

object | null

Null unless the subscriber redeemed a discount code. Then { code, kind }, where kind is discount or tracking (a code that changes no price). The amount the code took off is on the subscription’s first invoice. The SDK’s TypeScript types do not list this field yet.

string | null

boolean

true in live mode, false in test mode.

Example

{
  "id": "evt_3f2a1b0c9d8e7f6a",
  "type": "subscription.renewed",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "data": {
    "id": "b7e2a1c4-5d6f-4a8b-9c0d-1e2f3a4b5c6d",
    "status": "active",
    "plan_name": "Pro Monthly",
    "link_id": "4cbb8f52-7cf2-4480-8c66-34f794cd23d0",
    "currency": "EUR",
    "amount_minor": 1000,
    "current_period_end": "2026-09-19T12:00:00.000Z",
    "cancel_at_period_end": false,
    "pending_plan": null,
    "discount": null,
    "customer_email": "customer@example.com",
    "customer_name": "Alex Rivera",
    "livemode": true
  }
}

Dispute events

Fires when:

dispute.created: AgentaOS finds a new dispute on one of your sales.
dispute.closed: a dispute closes in your favor (status is won), or a bank inquiry closes without a chargeback (status is warning_closed). Either way the sale is released. A lost dispute sends no event: read it from the sale’s mor_status, which becomes charged_back.

A dispute starts when a buyer’s bank opens a chargeback on a sale, or first sends an inquiry about it (the warning_ statuses). Both events share the same data shape. transaction_id is the sale’s transaction id. For a one-time sale and for every subscription charge, it equals that charge’s checkout.session.completed id without the evt_ prefix, so keep those event ids and a dispute finds its sale, and for a renewal its metadata.subscriptionId. subscription.renewed cannot be matched to a dispute: its id is random and it carries no transaction id.

Hide data fields

string

The dispute’s id at the card processor.

string

The dispute’s status as the card processor reports it. On dispute.created: warning_needs_response, warning_under_review, needs_response, under_review, prevented, or lost when AgentaOS first sees a dispute that has already closed. On dispute.closed: won or warning_closed.

string

The sale the dispute is about.

number

Disputed amount in integer minor units. 4999 = €49.99.

string

Lowercase ISO code, e.g. "eur".

boolean

true in live mode, false in test mode.

Example

{
  "id": "evt_1a2b3c4d5e6f7a8b",
  "type": "dispute.created",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "data": {
    "dispute_id": "dp_1P...",
    "status": "needs_response",
    "transaction_id": "8c7d6e5f-4a3b-2c1d-0e9f-8a7b6c5d4e3f",
    "amount_minor": 4999,
    "currency": "eur",
    "livemode": true
  }
}

`account.updated`

Fires when: a business’s verification changes, in live mode only.

Its identity check is verified or declined.
Our reviewers approve, reject, hold or resume the business, or ask for a change.
Our reviewers verify or withdraw its identity by hand.

The event goes to the business and to the platform that manages it. The body is the state after the change.

Hide data fields

string

unverified, in_review, verified, on_hold, or rejected.

boolean

We asked the business for a change and are waiting on it.

boolean

The identity check is done. For another app of your own company, this is your company’s check.

boolean

Always true: verification is about live money. The event still reaches your endpoint while you build in test mode, because an account has one webhook endpoint.

Example

{
  "id": "evt_4e1b9a0c2d3f5a67",
  "type": "account.updated",
  "business": "5b1f0c2e-8a4d-4c7b-9e21-3f6a7d8c9b10",
  "data": {
    "verification": "verified",
    "changes_requested": false,
    "identity_verified": true,
    "livemode": true
  }
}

`webhook.test`

Fires when: you click Send test event in Settings → Developers → Webhooks. Use it to check that your endpoint receives and verifies events. It goes to your account’s webhook URL, signed like every other event.

Hide data fields

string

Always "Test event from AgentaOS".

boolean

true if you sent it from live mode, false from test mode.

Example

{
  "id": "evt_test_5c2e9a1f0b7d3e48",
  "type": "webhook.test",
  "business": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "data": {
    "message": "Test event from AgentaOS",
    "livemode": false
  }
}

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.

Platform webhooks

One endpoint for all the businesses you manage.

Getting started

Grow

Build with AI agents

Integrations

Sell

Platforms

Merchant of Record

Payouts

Webhooks

For customers

When each event fires

Event envelope

Which action fires which event

Your API calls

Actions outside your API calls

Which URL receives an event

Delivery and retries

Deduplication

Event order for subscriptions

`checkout.session.completed`

`send.completed`

`send.failed`

Subscription events

Dispute events

`account.updated`

`webhook.test`

Next steps

Verify signatures

Payment SDK: Webhooks

Platform webhooks

​When each event fires

​Event envelope

​Which action fires which event

​Your API calls

​Actions outside your API calls

​Which URL receives an event

​Delivery and retries

​Deduplication

​Event order for subscriptions

​checkout.session.completed

​send.completed

​send.failed

​Subscription events

​Dispute events

​account.updated

​webhook.test

​Next steps

Verify signatures

Payment SDK: Webhooks

Platform webhooks

When each event fires

Event envelope

Which action fires which event

Your API calls

Actions outside your API calls

Which URL receives an event

Delivery and retries

Deduplication

Event order for subscriptions

`checkout.session.completed`

`send.completed`

`send.failed`

Subscription events

Dispute events

`account.updated`

`webhook.test`

Next steps