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"
  }
}
  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.