Webhooks

AgentaOS pushes events to a URL you configure, rather than making you poll. Configure webhookUrl when you create a checkout or a payment link, or set one org-wide in the dashboard (Settings → Developers → Webhooks). A checkout’s own webhookUrl wins if set, then its payment link’s, then your org default, whichever is found first is the only one that fires, they don’t all fire.

If none of the three is set, nothing is sent. That’s not an error, it’s silent by design, so double check you’ve configured a URL somewhere in the chain before relying on webhooks.

Events

checkout.session.completed

Fired when a checkout’s payment is confirmed, on any rail (card, wallet, stablecoin). Resolved via the checkout’s own webhook, then its payment link’s, then your org default.

send.completed

Fired when an outbound on-chain send you initiated is confirmed. Only your org-level webhook URL is checked for this event (there’s no per-checkout scope for outbound sends).

send.failed

Fired when an outbound send’s broadcast fails. Same org-level-only resolution as send.completed.

`checkout.session.completed`

{
  "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" }
  }
}

string | null

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

string

The checkout’s public session_id.

string

Currency units, as a string ("49.99"), not a number. See Money model.

string

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

string | null

On-chain hash. 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

On-chain payer address. null for card/bank rails.

string

human or agent.

string

CAIP-2 network ID for on-chain rails, or stripe for card/bank.

boolean

true on a test-mode checkout.

number | null

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

object

Whatever you set on the checkout (or its link), unchanged.

`send.completed`

{
  "id": "evt_9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
  "type": "send.completed",
  "data": {
    "transaction_id": "9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a",
    "tx_hash": "0xabc123...",
    "from": "0xYourOrgWallet...",
    "to": "0xRecipient...",
    "amount": "100.00",
    "token": "USDC",
    "chain_id": 8453,
    "network": "eip155:8453",
    "testnet": false,
    "description": null
  }
}

`send.failed`

Identical shape to send.completed, with tx_hash: null.

{
  "id": "evt_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "type": "send.failed",
  "data": {
    "transaction_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "tx_hash": null,
    "from": "0xYourOrgWallet...",
    "to": "0xRecipient...",
    "amount": "100.00",
    "token": "USDC",
    "chain_id": 8453,
    "network": "eip155:8453",
    "testnet": false,
    "description": null
  }
}

The raw payload above is the literal snake_case JSON body AgentaOS POSTs to your webhookUrl, this is what you’ll parse in any language other than the SDK. agentaos.webhooks.verify() (Node.js) parses it and returns a camelCased, typed object instead: linkId, sessionId, txHash, payerType, etc. rail, vendor_reference, testnet, and overpaid_by_cents are additive fields not yet reflected in the SDK’s TypeScript types, they arrive on the wire regardless of language.

Delivery

Delivered as POST, Content-Type: application/json, body is the exact JSON shown above.
A 10 second timeout per attempt, up to 3 attempts total, exponential backoff between retries.
Redirects are not followed (a 3xx response counts as a failed attempt).
URLs resolving to private or internal addresses are rejected before any delivery attempt (SSRF guard).
Return 2xx quickly. Do slow work (emails, fulfillment) asynchronously after responding, a slow handler risks the delivery timing out and retrying.

Signature verification

Every delivery includes an X-AgentaOS-Signature header:

X-AgentaOS-Signature: t=1770379200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Part	Meaning
`t`	Unix timestamp (seconds) when the signature was generated.
`v1`	HMAC-SHA256 hex digest of `{t}.{raw request body}`, keyed with your webhook signing secret.

Get your signing secret (whsec_...) from app.agentaos.ai → Settings → Developers → Webhooks → Reveal signing secret. It’s stable across URL changes; rotate it from the same screen if it’s ever exposed.

SDK (Node.js)
Manual (any language)

import { AgentaOS, WebhookVerificationError } from '@agentaos/pay';
import express from 'express';

const agentaos = new AgentaOS(process.env.AGENTAOS_API_KEY!);

// Use express.raw(): verification needs the exact raw body bytes.
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = agentaos.webhooks.verify(
      req.body,
      req.headers['x-agentaos-signature'] as string,
      process.env.AGENTAOS_WEBHOOK_SECRET!,
    );

    if (event.type === 'checkout.session.completed') {
      fulfillOrder(event.data.sessionId);
    }

    res.sendStatus(200);
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return res.status(400).send('Invalid signature');
    }
    res.status(500).send('Webhook processing failed');
  }
});

import hmac, hashlib, time

def verify_webhook(raw_body: str, signature: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature.split(','))
    timestamp = int(parts['t'])

    # Reject signatures older than 5 minutes
    if abs(time.time() - timestamp) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, parts['v1'])

Verify against the raw request body bytes, before any JSON parsing or re-serialization. Re-stringifying a parsed object can reorder keys or change whitespace and silently break the signature check.

Best practices

Don't trust the redirect

A checkout’s successUrl is best-effort, the buyer’s browser might close first. Webhooks are the source of truth for “did this actually get paid.”

Handle idempotently

A retried delivery can arrive more than once. Deduplicate on id (the event id) or data.session_id/data.transaction_id.

Respond fast

Return 200 immediately, then do the slow work. A handler that blocks risks a retry and a duplicate delivery.

Verify before you trust

Never act on the raw body without checking X-AgentaOS-Signature first, anyone can POST to a public URL.

Next steps

Checkouts

Set webhookUrl when creating a checkout.

Payment Links

Set a default webhookUrl for every checkout created from a link.

SDK

CLI

API Reference

Events

`checkout.session.completed`

`send.completed`

`send.failed`

Delivery

Signature verification

Best practices

Don't trust the redirect

Handle idempotently

Respond fast

Verify before you trust

Next steps

Checkouts

Payment Links

​Events

​checkout.session.completed

​send.completed

​send.failed

​Delivery

​Signature verification

​Best practices

Don't trust the redirect

Handle idempotently

Respond fast

Verify before you trust

​Next steps

Checkouts

Payment Links

Events

`checkout.session.completed`

`send.completed`

`send.failed`

Delivery

Signature verification

Best practices

Next steps