Seismic Card Issuance API

Inbound — Core API (target)

Provider webhooks are received by the Seismic Card Issuance API. Register these HTTPS URLs in each vendor dashboard (use your environment host).

Provider	Path	Sandbox	Production
Sumsub	`POST /v1/webhooks/sumsub`	`https://api.seismic-cards.systems/v1/webhooks/sumsub`	`https://api.seismic-cards.systems/v1/webhooks/sumsub`
Card issuer	`POST /v1/webhooks/interlace`	`https://api.seismic-cards.systems/v1/webhooks/interlace`	`https://api.seismic-cards.systems/v1/webhooks/interlace`
Dynamic	`POST /v1/webhooks/dynamic`	`https://api.seismic-cards.systems/v1/webhooks/dynamic`	`https://api.seismic-cards.systems/v1/webhooks/dynamic`

Env var	Purpose
`PUBLIC_API_URL`	Public Core API base (drives `sumsubWebhookUrl` when mode is `seismic`)
`SUMSUB_WEBHOOK_MODE=seismic`	Route Sumsub callbacks to Core API (required for cutover)
`SUMSUB_WEBHOOK_SECRET`	HMAC verification for Sumsub
`INTERLACE_WEBHOOK_SECRET`	Signature verification for card-issuer webhooks
`DYNAMIC_WEBHOOK_SECRET`	HMAC verification for Dynamic (`x-dynamic-signature-256`)

GET /v1/kyc/config returns sumsubWebhookUrl and sumsubWebhookMode for your environment — use that URL when registering Sumsub. After hosted Sumsub verification, you can still call POST /v1/applicants/{id}/submit to sync tenant KYC and trigger issuer handoff. Poll GET /v1/applicants/{id}/kyc-status for issuer progress — see KYC integration. Cutover steps (dashboards + Railway env): see scripts/aws/WEBHOOK_CUTOVER.md in the monorepo.

Legacy — seismic-cards (migration only)

Older deployments used the seismic-cards Railway service with SUMSUB_WEBHOOK_MODE=seismic and path /webhooks/sumsub (no /v1). That path is legacy — do not register new Sumsub webhooks there. Keep seismic only until the Sumsub dashboard points at Core API, then set SUMSUB_WEBHOOK_MODE=seismic.

	Legacy (do not use for new setup)
URL	`https://api-production-XXXX.up.railway.app/webhooks/sumsub`
Mode	`SUMSUB_WEBHOOK_MODE=seismic` + `SEISMIC_SUMSUB_WEBHOOK_URL`

Outbound — Seismic → your app

Seismic will send outbound webhooks to your endpoint so you can react to events without polling — an applicant is approved, a card changes state, or a credit purchase settles.

Outbound delivery is not yet available on all endpoints (POST /v1/webhooks returns not implemented). The sections below describe the planned contract.

Delivering events

You register an HTTPS endpoint and the events you care about. Seismic POSTs a JSON body to that URL for each matching event.

Example event

{
  "id": "evt_abc123",
  "type": "card.activated",
  "createdAt": "2026-07-07T10:15:00.000Z",
  "data": { "id": "card_abc123", "status": "ACTIVE" }
}

Verifying signatures

Each delivery is signed with the secret from your webhook subscription. Compute an HMAC-SHA256 over the raw request body and compare it, in constant time, to the signature header.

import crypto from "node:crypto";

function verify(rawBody: string, signature: string, secret: string): boolean {
  const digest = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(digest);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Always verify against the raw request body before parsing JSON. Reject any request whose signature does not match.

Best practices

Respond fast

Return 2xx immediately and process asynchronously. Slow handlers risk timeouts and retries.

Be idempotent

Deliveries may repeat. De-duplicate on the event id.

Verify every time

Check the signature on every request, not just the first.

Use HTTPS

Only register TLS endpoints so payloads stay encrypted in transit.

Get started

Core concepts

Reference

Webhooks

Inbound — Core API (target)

Legacy — seismic-cards (migration only)

Outbound — Seismic → your app

Delivering events

Verifying signatures

Best practices

Respond fast

Be idempotent

Verify every time

Use HTTPS

​Inbound — Core API (target)

​Legacy — seismic-cards (migration only)

​Outbound — Seismic → your app

​Delivering events

​Verifying signatures

​Best practices

Respond fast

Be idempotent

Verify every time

Use HTTPS

Inbound — Core API (target)

Legacy — seismic-cards (migration only)

Outbound — Seismic → your app

Delivering events

Verifying signatures

Best practices