Webhooks are the authoritative event stream for card activity and master-account ledger movements.

Delivery Contract

Header Value Notes
Content-Type application/json Always UTF-8 JSON.
x-client-id Your tenant ID Mirrors the API credential.
x-signature HMAC-SHA256 sha256=<hex> computed with client secret.
x-request-id UUID Request trace identifier.
x-idempotency-key Optional Propagated when the source API call had one.

Payload schema:

{
  "event": "card_transaction",
  "data": {
    "id": "5b2fa934-1f1d-4b71-8d5a-a3e2f61ac1af",
    "cardId": "0b1e9c6e-5d87-4f90-8c4d-0ad6f4ce4be5",
    "transactionAmount": "12.34",
    "transactionCurrency": "USD",
    "type": "authorization",
    "referenceId": "c8de3ebf-5b2d-4020-a7bb-65f88c3a37ce",
    "timestamp": "2025-06-02T11:24:12Z"
  }
}

Recommended Ingestion Flow

  1. Verify x-signature before parsing payload.
  2. Persist raw payload keyed by data.id.
  3. Handle duplicates idempotently.
  4. Return 204 No Content quickly.
  5. Process business logic asynchronously.

Event Types

Event Fired When Key Fields
card_transaction Authorizations, settlements, adjustments, refunds, declines, card lifecycle events cardId, type, referenceId, linkedId
account_transaction Master-account ledger entries (holds, releases, fees, transfers) accountId, type, subtype, amount, referenceId

Join events by referenceId for full flow reconciliation.

Replay Strategy

If your endpoint was unavailable, replay failed deliveries:

curl -X POST "$PAYCA_BASE_URL/v1/webhooks/resend?fromDate=2025-06-01T00:00:00Z" \
  -H "x-client-id: $PAYCA_CLIENT_ID" \
  -H "x-client-secret: $PAYCA_CLIENT_SECRET"

Recommendations:

  • Replay in chronological order.
  • Rate-limit replay processing to avoid 429.
  • Monitor replay completion and remaining failures.
  • Use response counters (account, card, total) to validate scope.

Client-Side Storage Recommendations

Store at least these fields from every webhook:

  • Envelope: event, receive timestamp, HTTP headers (x-request-id, x-idempotency-key).
  • Data object: id, referenceId, type, subtype, amount, currency, cardId, accountId (when present).

This is sufficient for replay, audit, and financial reconciliation.

Alerting & Security

  • Alert when webhook failures spike or replay backlog grows.
  • Track end-to-end webhook latency.
  • Serve webhook endpoints over HTTPS (TLS 1.2+).
  • Rotate secrets regularly and support overlap during key rotation.

Continue with Webhook Balance Effects for event-by-event balance impact.