Webhooks - Agentcard

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.

curl -X POST https://api.agentcard.sh/api/v2/webhook_endpoints \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/agentcard/webhooks", "enabled_events": ["vault.*", "checkout_authorization.*", "order.*"]}'

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:

{
  "id": "evt_9f8e7d6c5b4a",
  "type": "vault.card_stored",
  "created": 1757264400,
  "livemode": false,
  "data": { }
}

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.

Verify the signature

Each delivery carries an AgentCard-Signature header:

AgentCard-Signature: t=1757264400,v1=5257a869e7…

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.

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)

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

No tunnel needed. The CLI registers a listener endpoint and forwards every event to your machine, signed exactly like production:

agent-cards companies webhooks listen --forward-to localhost:4242/webhooks
agent-cards companies webhooks test

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, wallet_link.opened, 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

Wallet

user_wallet.funding_detected, user_wallet.funded

Rewards and merchants

reward.*, merchant.connected

Company wallet

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

​Connect an endpoint

​The envelope

​Verify the signature

​Delivery and retries

​Develop locally

​Sandbox

​Events by object