Webhooks API

Manage the webhook subscriptions of your program. For signature verification, retries, and the full event catalog, see the Webhooks guide.

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.

POST /webhooks

Create a subscription.

// Request
{
  "url": "https://api.yourproject.com/hooks/web3card",
  "events": ["transaction.*", "kyc.*", "vault.credited"]
}

// Response
{
  "id": "wh_2210",
  "url": "https://api.yourproject.com/hooks/web3card",
  "events": ["transaction.*", "kyc.*", "vault.credited"],
  "status": "active",
  "secret": "whsec_9k3j…"
}

The secret is returned only on creation. Store it securely; it signs every delivery.

GET /webhooks

List your subscriptions.

GET /webhooks/{id}

Retrieve a subscription and its recent delivery stats.

PATCH /webhooks/{id}

Update the URL or event selection.

DELETE /webhooks/{id}

Delete a subscription. Pending retries are cancelled.

POST /webhooks/{id}/rotate-secret

Rotate the signing secret. The old secret keeps validating deliveries for one hour to allow zero-downtime rotation.

POST /webhooks/{id}/test

Send a signed ping event to your endpoint to validate connectivity end to end.

// Response
{ "delivered": true, "responseStatus": 200, "latencyMs": 184 }

Delivery format

{
  "id": "evt_88d1",
  "type": "transaction.created",
  "createdAt": "2026-07-19T14:00:00Z",
  "data": { … }
}

Headers on every delivery:

Header	Content
X-W3C-Signature	HMAC SHA-256 of the raw body
X-W3C-Event-Id	Event id, for idempotent processing
X-W3C-Event-Type	Event type