Skip to main content
Everything that happens to your connected users reaches your server as a webhook: a card stored in the Vault, a checkout approved, an order placed, an identity check finished. SDK callbacks are UI signals. Webhooks are the record.

Connect an endpoint

Register a URL and the events it should receive. Do it once per mode: a sandbox token registers a sandbox endpoint, a production token a production one.
The response carries the endpoint’s secret once. Store it. enabled_events takes exact names, prefix wildcards like vault.*, or ["*"] for everything. An endpoint receives only what it lists. Manage endpoints, read or rotate the secret, and inspect recent deliveries with the Webhook endpoints API. The same is available in the dashboard under Developers → Webhooks.

The envelope

Every event has the same shape:
type is stable and part of the API contract, so branch on it directly. livemode: false is sandbox. Delivery is at least once, so deduplicate on id.

Keep only your own events

Every endpoint in your company receives every event of its mode. To run a staging and a production backend against one company, give each backend its own OAuth client and read data.origin.client_id on every event:
origin.client_id names the OAuth client whose call made what the event is about: the vault session it minted, the purchase it started with /buy, the checkout authorization it created, or the wallet link it made. Each backend keeps the events that name its own client and returns a 2xx for the rest. Any other status counts as a failed delivery, and Agentcard retries it. origin.client_id is null when Agentcard has no client on record for the object, such as a card issued with POST /api/v2/cards or with an API key.

Verify the signature

Each delivery carries an AgentCard-Signature header:
Take t, join it to the raw request body with a dot, compute HMAC-SHA256 with your endpoint’s secret, and compare it to v1 in constant time. Reject timestamps older than a few minutes to block replays. Verify against the raw bytes, never re-serialized JSON.
A legacy X-AgentCard-Signature: sha256=… header signs the body alone. New integrations should use AgentCard-Signature.

Delivery and retries

Return a 2xx quickly and do slow work afterwards. A slow handler looks like a failure. Failed deliveries retry up to five times: immediately, then after 1 minute, 5 minutes, 30 minutes, and 1 hour. Recent deliveries with payloads and response codes are on List recent deliveries and in the dashboard.

Develop locally

Expose your local server with a tunnel, then create a sandbox endpoint for the tunnel’s URL with Create a webhook endpoint. Every sandbox event reaches your machine, signed exactly like production. Delete the endpoint with Delete a webhook endpoint when you are done.

Sandbox

Sandbox events deliver exactly like production, with livemode: false. Endpoints are scoped to one mode: if your sandbox integration completes actions but nothing arrives, check that the endpoint was created with a sandbox token.

Events by object

Connections

connection.created, approval.requested

Vault

vault.session_linked, vault.card_stored

Checkout authorizations

approved, submitted, declined, expired, amount_mismatch

Orders

order.placed, order.confirmed, order.failed

Cards and transactions

card.*, transaction.*, balance.low

Identity verification

identity.verification.updated

Rewards and merchants

reward.*, merchant.connected

Company wallet

cardholder.*, card_flow.*, transfer.*, recovery.*, wallet.*