Webhooks

Webhooks push events to your backend in real time: transactions, KYC results, vault credits, card and order status changes. They are the backbone of a responsive card UX.

API v1 · Legacy

This page is part of the reference of the first version of the Web3Card API, kept here for reference. API v1 does not take new integrations: API v2 replaces it, and the platform today works as described in the rest of this manual.

Subscribe

Register your endpoint and select the events you want:

curl -X POST https://api.web3card.dev/v1/webhooks \
  -H "Authorization: Bearer w3c_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourproject.com/hooks/web3card",
    "events": ["transaction.*", "kyc.*", "vault.credited", "card_order.updated"]
  }'

{ "id": "wh_2210", "status": "active", "secret": "whsec_9k3j…" }

Verify signatures

Every delivery is signed. Compute an HMAC SHA-256 of the raw body with your webhook secret and compare it to the X-W3C-Signature header:

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Reject any delivery whose signature does not match.

Event catalog

Event	Emitted when
transaction.created	A new authorization is approved or declined
transaction.updated	A transaction changes status (settled, refunded, disputed…)
vault.credited	A top-up is credited to a vault
vault.debited	A settlement or withdrawal leaves a vault
kyc.approved	Identity verification approved
kyc.rejected	Identity verification rejected
card.updated	Card status change (frozen, lost, voided…)
card_order.updated	Physical card order progresses

Delivery and retries

Deliveries expect a 2xx response within 10 seconds. Failed deliveries are retried with exponential backoff for up to 24 hours. Events are delivered at least once; use the event id for idempotent processing.