Atlas Transaction Webhooks

The Atlas Webhooks API delivers asynchronous, real-time HTTP POST notifications to your webhook listener whenever payment transactions progress through clearing, settlement, dispute, or failure lifecycles.

Instead of continuously polling payment status endpoints, your server can subscribe to webhooks to update client orders, release goods, credit merchant ledgers, and trigger automated reconciliation workflows.

sequenceDiagram
    autonumber
    actor Customer as Customer / Payer
    participant Bank as Clearing Partner (ClearBank / SEPA / SWIFT)
    participant Atlas as Atlas Payment Service
    participant Listener as Your Webhook Listener

    Customer->>Bank: Send Inbound Deposit (IBAN)
    Bank->>Atlas: Settlement Notification
    Atlas->>Listener: POST /webhook (ibanToWallet.completed)
    Note over Listener: Validate X-Atlas-Signature & Process
    Listener-->>Atlas: 200 OK
    Atlas->>Atlas: Mark Webhook Delivery as Success

---

Supported Webhook Categories

The Transaction Webhooks API provides dedicated payload schemas for each transaction type and status combination:

Category	Event Name	State	Description
IBAN to Wallet	ibanToWallet.requested	requested	Inbound deposit recognized, awaiting settlement.
IBAN to Wallet	ibanToWallet.completed	completed	Funds settled and credited to your virtual IBAN wallet.
IBAN to Wallet	ibanToWallet.disputed	disputed	Inbound deposit recalled or disputed by originating bank.
IBAN to Wallet	ibanToWallet.archived	archived	Inbound deposit cancelled or archived.
Wallet to Wallet	walletToWallet.completed	completed	Internal transfer finished (fires for both sender & receiver).
Wallet Credit	wallet.credit.success	completed	VPay inter-company payment credited to receiver wallet.
Wallet to Account	walletToAccount.requested	requested	Outbound payout validated and queued for bank rails.
Wallet to Account	walletToAccount.completed	completed	Outbound payout successfully settled to beneficiary bank.
Wallet to Account	walletToAccount.archived	archived	Outbound payout failed or cancelled by clearing rail.
Wallet to Account	walletToAccount.refunded	refunded	Outbound payout returned and principal refunded to wallet.

---

Security & Signature Verification

Every incoming webhook contains security headers to verify message authenticity and prevent replay attacks:

POST /api/webhooks/atlas HTTP/1.1
Host: your-api-domain.com
Content-Type: application/json
X-Atlas-Signature: t=1705315800,v1=9b7c8932ef216f40b2a8d3...
X-Atlas-Delivery-Id: 550e8400-e29b-41d4-a716-446655440000

Verification Algorithm

1. Extract timestamp t and signature v1 from the X-Atlas-Signature header.
2. Ensure t is within an acceptable window (e.g. 5 minutes) to protect against replay attacks.
3. Compute the HMAC SHA-256 digest of ${t}.${rawRequestBody} using your Webhook Secret Key.
4. Compare the computed signature using a constant-time comparison.

import crypto from 'crypto';

function verifyAtlasWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(',').map(s => s.split('=')));
  const timestamp = parts.t;
  const signature = parts.v1;

  // Check timestamp freshness (5 minutes)
  const tolerance = 5 * 60;
  if (Math.abs(Date.now() / 1000 - parseInt(timestamp, 10)) > tolerance) {
    throw new Error('Webhook timestamp too old or in future');
  }

  // Compute expected HMAC
  const payloadToSign = `${timestamp}.${rawBody}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payloadToSign)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

---

Response Expectations & Retries

• Immediate Acknowledgment: Return an HTTP 200 OK or 204 No Content status within 5 seconds of receiving the notification.
• Asynchronous Processing: Queue intensive operations (such as generating PDFs or emailing users) for background worker processing.
• Retry Schedule: If your listener returns a non-2xx status or times out, Atlas retries delivery up to 8 times using exponential backoff with jitter (initial retry after 30s, scaling up to 24 hours).
• Idempotent Handling: Use the unique reference or id field in the payload to guard against processing duplicate deliveries.