Wallet to Wallet - Completed Webhook

Overview

The walletToWallet.completed webhook fires when funds move between two wallets. Two separate webhook notifications are emitted: one for the debited source wallet (transactionType: "debit") and one for the credited target wallet (transactionType: "credit").

• Event Name: walletToWallet.completed
• Target State: completed
• HTTP Method: POST (Sent from Atlas to your configured webhook listener URL)

---

Webhook Headers

Header	Description
Content-Type	application/json
X-Atlas-Signature	HMAC SHA-256 signature and timestamp for message authentication
X-Atlas-Delivery-Id	Unique UUID tracking this webhook delivery attempt

---

Payload Schema

Payload Fields

Field	Type	Description
id	integer	Unique transaction record ID.
amount	number	Numerical amount transferred (e.g. 250).
reference	string	Internal transfer reference (e.g. "REF-W2W-002").
state	string	Current state ("completed").
currency	string	ISO currency code (e.g. "GBP").
type	string	Transaction type ("wallet_to_wallet").
walletId	integer	Current wallet context for this event notification.
transactionType	string	Leg of the transfer: "credit" or "debit".
toWalletId	integer	Destination wallet ID.
fromWalletId	integer	Source wallet ID.
createdDate	string	Timestamp when transfer was initiated.
completedDate	string	Timestamp when transfer completed.
companyId	integer	Company ID owning the wallet.
clientReference	string	Custom client reference if supplied.
externalUniqueRef	string	External idempotency reference if provided.

Example Payload

{
  "id": 10002,
  "amount": 250,
  "reference": "REF-W2W-002",
  "state": "completed",
  "currency": "GBP",
  "type": "wallet_to_wallet",
  "walletId": 3001,
  "transactionType": "credit",
  "toWalletId": 3001,
  "fromWalletId": 3002,
  "createdDate": "2024-01-15T11:00:00Z",
  "completedDate": "2024-01-15T11:00:05Z",
  "companyId": 456
}

---

Expected Response

Your endpoint must respond with an HTTP 200 OK status code within 5 seconds to acknowledge delivery:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}

---

Handling Example

// Express.js Webhook Handler
app.post('/api/webhooks/atlas', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-atlas-signature'];

  try {
    // 1. Verify webhook signature
    verifySignature(req.body, signature, process.env.ATLAS_WEBHOOK_SECRET);

    const event = JSON.parse(req.body.toString());

    // 2. Handle walletToWallet.completed
    if (event.state === 'completed') {
      console.log(`Processing Wallet to Wallet - Completed Webhook: Reference ${event.reference}, Amount: ${event.amount} ${event.currency}`);
      // Update your internal order or ledger state
    }

    // 3. Acknowledge receipt
    res.status(200).json({ status: 'received' });
  } catch (err) {
    console.error('Webhook verification failed:', err.message);
    res.status(400).send('Invalid signature');
  }
});

---

Interactive Payload Schema & Example

Review the full JSON schema and test response handling: