Webhooks

CardNexus sends webhook events to your registered endpoints when something happens on your account that's worth knowing about — an order is placed, a payout settles, a listing is updated, a dispute opens.

Status: webhook subscriptions are coming soon. This page documents the model so integrations can plan around it; the configuration UI and the event catalogue land in an upcoming release.

How delivery works

Webhooks are delivered through Svix, a managed delivery service. Svix handles signing, retries with exponential backoff, replay of failed deliveries, and the embedded portal where you'll manage subscriptions and inspect delivery logs.

When the event catalogue is live, you'll:

Open Settings → Webhooks at cardnexus.com.
Add an endpoint (your HTTPS URL).
Pick the event types you care about.
CardNexus signs every delivery; you verify the signature server-side before trusting the payload.

Signature verification

Every delivery carries three headers:

Header	Meaning
`webhook-id`	Unique per delivery. Use for idempotency / deduplication on your side.
`webhook-timestamp`	Epoch seconds at send time. Reject deliveries older than ~5 min to mitigate replay.
`webhook-signature`	HMAC-SHA256 of `id.timestamp.body` keyed with your endpoint's signing secret.

Svix publishes verified libraries for Node.js, Python, Go, Ruby, PHP, Rust, Java, C#, and Elixir — use them rather than rolling your own HMAC. Their docs cover each runtime: docs.svix.com.

Event envelope

Every webhook payload follows the same shape:

{
  "id": "evt_2QgFh4kP9xR8yJ5mN3wQzL7vT",
  "type": "order.placed",
  "createdAt": "2026-04-26T10:32:00.000Z",
  "version": "v1",
  "data": {
    "orderId": "65f3a2b1c8d4e9f7a6b5c4d3"
  }
}

Field	Meaning
`id`	Stable event id. Cache and dedupe on this.
`type`	Dotted event name (`order.placed`, `payout.settled`, etc.).
`createdAt`	When the event fired (UTC, ISO 8601).
`version`	Envelope version. `v1` today; future incompatible payload changes mint a new version.
`data`	Per-event payload. Schema documented per event type in the API reference.

Acknowledging

Return 2xx to acknowledge a delivery. Anything else (including timeouts > 15s) is treated as a failure and retried by Svix per its backoff policy. Don't return 4xx for "I don't recognise this event type" — log it and 2xx instead, otherwise the event keeps retrying forever.

What to expect next

The full event catalogue, the subscription UI, and the embedded delivery dashboard ship together. This page is documented today so integrations can stub out the receiving side ahead of time.

Pagination

Overview