Webhooks

Webhooks

The Business Webhook System lets business clients receive real‑time notifications when transactions complete (for example CAD‑INTERAC deposits and withdrawals).
Webhook delivery is tightly integrated with business API keys and uses HMAC signatures for verification.

High-level flow

  1. Quote / transaction creation
    • A business user initiates a transaction (typically via the Quote APIs).
  2. Internal webhook handling
    • Transfaar receives provider webhooks, updates quotes, transactions and ledger entries.
  3. Business webhook fan‑out
    • If the user is a business client with a configured webhook URL on their API key, Transfaar enqueues a webhook job and delivers a business webhook to the URL you configured.

Payload schema

Business webhooks use a unified payload for deposits and withdrawals, distinguished by transaction_type:

{
  "event_type": "deposit_completed",
  "sender": {
    "email": "sender@example.com",
    "first_name": "John",
    "last_name": "Doe"
  },
  "recipient": {
    "email": "recipient@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "account_id": "beneficiary-uuid"
  },
  "amount_with_fees": "105.00",
  "amount": "100.00",
  "currency": "CAD",
  "status": "COMPLETED",
  "timestamp": "2024-01-01T00:00:00Z",
  "reference": "transaction-reference",
  "transaction_type": "deposit",
  "transaction_id": "transaction-uuid"
}

Key fields:

  • event_type: "{transaction_type}_{status}", e.g. "deposit_completed", "withdrawal_failed".
  • transaction_type: DEPOSIT, WITHDRAWAL, or EXCHANGE.
  • status: current transaction status (for example COMPLETED).
  • reference: the Transfaar transaction reference you can use to reconcile.
  • transaction_id: unique internal transaction identifier.

Webhook security

Webhooks are signed with the same secret key associated with your business API key.

Headers:

  • Content-Type: application/json
  • User-Agent: Transfaar-Business-API/1.0
  • X-Transfaar-Signature: <hmac_signature>

Verification:

  1. Read the raw request body as a string.
  2. Recompute HMAC-SHA256 over the body (and any additional fields described in the Business Webhook design) using your stored secret key.
  3. Compare the hex‑encoded result with X-Transfaar-Signature using a constant‑time comparison.

If the signatures don’t match, you must reject the webhook.

Delivery semantics and retries

Internally, webhooks are processed by a background WebhookService that:

  • Pushes webhook jobs to a queue for non‑blocking delivery.
  • Implements retries with exponential backoff (up to 3 attempts) on network or 5xx failures.
  • Logs all failed deliveries for later inspection, without blocking the main transaction flow.

Manual testing

For sandbox/testing environments, Transfaar exposes external endpoints that can be used to re‑send or simulate webhook delivery for a given transaction reference.
When you use these endpoints, standard business authentication (HMAC headers) applies, and your webhook URL must already be configured on a /business API key.

AuthenticationAPI