Webhooks

Register an HTTPS endpoint with POST /v1/webhooks. Apocor POSTs a signed JSON envelope for each matching domain event. Events are also available via GET /v1/events?starting_after= (same ids as webhooks) for reconciliation.

Example event

{
  "id": "evt_abc123",
  "type": "card.activated",
  "created": "2026-07-07T10:15:00.000Z",
  "environment": "LIVE",
  "sequence": 3,
  "data": { "id": "card_abc123", "status": "ACTIVE" }
}

Event catalog

Type	When
`applicant.status_changed`	Every KYC / issuer KYC status change
`card.created`	Issuance succeeded
`card.issuance.failed`	Issuance dead-lettered
`card.activated` / `frozen` / `unfrozen` / `blocked` / `closed`	API or issuer lifecycle
`card.funded` / `card.funding_failed`	Fund / defund / fund-from-wallet
`transaction.authorized` / `declined` / `cleared` / `reversed` / `refunded`	Issuer spend webhooks
`program.*` / `account.created`	Program and account CRUD

Full machine-readable list: GET /v1/webhooks/event-types.

Events fire only on actual state changes. Freezing an already-frozen card returns 200 but emits no second card.frozen. Likewise applicant.status_changed fires only when the tenant-visible status changes — internal verification stages that don’t move the collapsed status stay silent, and concurrent processing paths are deduped so each transition is emitted once.

Verifying signatures

Header: X-Webhook-Signature: t=<unix_ts>,v1=<hex>
Signed payload: {timestamp}.{raw_body} with HMAC-SHA256 using your endpoint secret.

import crypto from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5 min skew
  const digest = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(v1));
}

During secret rotation (POST /v1/webhooks/{id}/rotate-secret), verify against the new secret or the previous secret until previous_secret_expires_at (48h overlap). Also sent: X-Webhook-Id (immutable event id — dedupe on this), X-Webhook-Event.

Latency

First delivery attempt is typically 1–2 seconds after Apocor persists the event (target under 5 seconds). This is after our commit, not a synchronous hook on the card-network authorization path. We retry up to 6 times with backoff, then dead-letter. Return 2xx immediately and process asynchronously.

Managing subscriptions

Action	Endpoint
List subscriptions	`GET /v1/webhooks`
Create (secret returned once)	`POST /v1/webhooks`
Update URL / event filter / status	`PATCH /v1/webhooks/{id}`
Delete	`DELETE /v1/webhooks/{id}`
Send a synthetic test event	`POST /v1/webhooks/{id}/test`
Delivery log (attempts, status, response codes)	`GET /v1/webhooks/{id}/deliveries`
Re-send one delivery	`POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver`
Rotate signing secret (48h dual-secret overlap)	`POST /v1/webhooks/{id}/rotate-secret`

Redelivered events carry the same event id — receivers that dedupe on X-Webhook-Id handle them for free.

Reconcile missed events

Primary: GET /v1/events?starting_after={last_event_id}&limit=100
Resource GETs: KYC status, card, issuance, transactions, funding balances
Delivery log: GET /v1/webhooks/{id}/deliveries + redeliver

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.

Issuance notes

POST /v1/cards requires Idempotency-Key (72h window). Optional reference_id — unique per program + environment; query with GET /v1/cards?reference_id=.
Async: 202 + issuance_id; poll GET /v1/cards/issuances/{id}.
In-flight same key → 409 with issuance_id.
POST /v1/cards/{id}/fund, fund-from-wallet, and defund also require Idempotency-Key.

Get started

Core concepts

Webhooks & events

Reference

Event catalog

Verifying signatures

Latency

Managing subscriptions

Reconcile missed events

Best practices

Respond fast

Be idempotent

Verify every time

Use HTTPS

Issuance notes

​Event catalog

​Verifying signatures

​Latency

​Managing subscriptions

​Reconcile missed events

​Best practices

Respond fast

Be idempotent

Verify every time

Use HTTPS

​Issuance notes

Event catalog

Verifying signatures

Latency

Managing subscriptions

Reconcile missed events

Best practices

Issuance notes