Skip to main content

​
Test mode

Webhook endpoints registered with an sk_test_* (test mode) API key receive events with livemode: false. Endpoints registered with an sk_live_* key receive livemode: true events. Use a separate endpoint per mode — your dev receiver should not see production traffic, and vice versa.

​
Local development with ngrok

AgentCard cannot POST to localhost — it has no route to your machine. Use a tunnel: 
# 1. Start your receiver locally
npm run dev   # listening on http://localhost:3000

# 2. In another shell, expose it
ngrok http 3000
# → https://abc123.ngrok-free.app

# 3. Register that URL as a webhook endpoint
agent-cards-admin webhooks create \
  --url https://abc123.ngrok-free.app/webhooks/agentcard \
  --events 'card.*,transaction.*'
Trigger a real event — e.g. create a test card — and watch your receiver fire.

​
Inspecting deliveries

Every delivery attempt is recorded. Use the CLI to see recent attempts for an endpoint: 
agent-cards-admin webhooks deliveries wh_abc123 --limit 20
You’ll see status (success / failed / pending), attempt count, HTTP response code, and timestamps. Failed deliveries are retried up to 5 times — the row tracks each attempt.

​
Triggering events on demand

There is no dedicated “send a test event” endpoint yet — instead, perform the real operation in test mode:
To test…Run
card.createdagent-cards-admin cards create
card.closed (manual)agent-cards-admin cards close <card-id>
cardholder.createdagent-cards-admin cardholders create
cardholder.updatedPATCH /api/v1/cardholders/:id
transaction.authorizedUse the card’s PAN at a test merchant in test mode
Each of these emits the corresponding webhook to all subscribed endpoints in your org.

​
Common failure modes

SymptomCauseFix
failed deliveries with HTTP 400Signature mismatch — usually because the receiver reparses the JSON before signingUse the raw request bytes (see Verify signatures)
All deliveries time outYour receiver responds slower than 10sAcknowledge with 2xx first, do work async
Endpoint auto-disabled7 consecutive days of failuresFix the receiver, then PATCH /webhook_endpoints/:id with status: "active" to re-enable
Some events never arriveEndpoint not subscribed to that typeCheck enabled_events — use prefix wildcards like card.* for forward-compat