Webhooks

Everything that happens in the wallet reaches your server as a webhook. The SDK callbacks are UI signals; webhooks are the record. Create endpoints in the dashboard under Webhooks, or with agent-cards companies webhooks create.

The envelope

Every event has the same shape:

{
  "id": "evt_...",
  "type": "connected_card.updated",
  "created": "2026-08-11T18:30:00.000Z",
  "livemode": false,
  "data": { ... }
}

Delivery is at least once, so the same event can arrive twice. Deduplicate on id.

Verify the signature

Each delivery carries an AgentCard-Signature header:

AgentCard-Signature: t=1754938200,v1=5257a869e7...

To verify: take t, concatenate it with a dot and the raw request body, compute HMAC-SHA256 with your endpoint’s signing secret, and compare it to v1. Reject anything older than a few minutes to block replays.

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto
  .createHmac("sha256", process.env.AGENTCARD_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

import hmac, hashlib, os

t, v1 = (part.split("=", 1)[1] for part in header.split(","))
expected = hmac.new(
    os.environ["AGENTCARD_WEBHOOK_SECRET"].encode(),
    f"{t}.{raw_body}".encode(),
    hashlib.sha256,
).hexdigest()
valid = hmac.compare_digest(expected, v1)

Read the signing secret in the dashboard, or with companies webhooks reveal. If it leaks, companies webhooks roll-secret rotates it. There is also a legacy X-AgentCard-Signature: sha256=... header signing the body alone. New integrations should use AgentCard-Signature.

Delivery and retries

Failed deliveries retry with backoff, and a sweeper picks up anything that got interrupted. Recent deliveries, with payloads and response codes, are visible in the dashboard and with companies webhooks deliveries. Send yourself a test event any time:

agent-cards companies webhooks test

Every event we send

By default an endpoint receives everything. You can filter to specific types per endpoint.

Object	Events
Connections	`connection.created`
Added cards	`connected_card.updated`
Identity	`identity.verification.updated`
Cards	`card.created` · `card.updated` · `card.closed`
Cardholders	`cardholder.created` · `cardholder.updated` · `cardholder_onboarding_session.completed`
Transactions	`transaction.authorized` · `transaction.declined` · `transaction.cleared` · `transaction.voided`
Card flows	`card_flow.started` · `card_flow.failed`
Approvals	`approval.requested`
Balance	`wallet.funded` · `user_wallet.funded` · `wallet.balance.low` · `balance.low`
Transfers	`transfer.initiated` · `transfer.approved` · `transfer.completed` · `transfer.failed` · `transfer.released`
Recoveries	`recovery.requested` · `recovery.completed` · `recovery.rejected`
Withdrawals	`wallet.withdrawal.initiated` · `wallet.withdrawal.completed` · `wallet.withdrawal.failed`
Wallet links	`wallet_link.opened`
Rewards	`reward.earned` · `reward.reversed`
Merchants	`merchant.connected`
Platform	`platform_connect_session.completed`

When it fails

If your endpoint is down, deliveries retry; nothing is lost, but act on the dashboard’s failure indicators. If signatures stop verifying, check that you’re reading the raw body (not re-serialized JSON) and the right endpoint’s secret.

Sandbox behavior

Sandbox events deliver exactly like production, with livemode: false. The quickstart’s events are real deliveries you can inspect. Next: Purchase API

Get started

The wallet

Platforms

Purchase

Tools

Ship

The envelope

Verify the signature

Delivery and retries

Every event we send

When it fails

Sandbox behavior

​The envelope

​Verify the signature

​Delivery and retries

​Every event we send

​When it fails

​Sandbox behavior

The envelope

Verify the signature

Delivery and retries

Every event we send

When it fails

Sandbox behavior