Wallet to Account - Requested Webhook

Overview

The walletToAccount.requested webhook fires immediately after an outbound payout (WALLET_PAYOUT) is submitted and accepted for processing by Atlas.

• Event Name: walletToAccount.requested
• Target State: requested
• 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 payment transaction ID.
amount	string	Transfer amount formatted as string (e.g. "1000.00").
reference	string	Unique order tracking reference (e.g. "REF-W2A-003").
state	string	Lifecycle state ("requested").
currency	string	Currency code (e.g. "USD").
type	string	Transaction type ("wallet_to_account").
walletId	integer	Debited funding wallet ID.
createdDate	string	Creation timestamp.
account	object	Target beneficiary bank account details.
account.id	integer	Beneficiary account ID.
account.accountNumber	string	Beneficiary bank account number.
account.bankName	string	Beneficiary bank name.
account.beneficiaryFirstName	string	Beneficiary first name (for individual).
account.beneficiaryLastName	string	Beneficiary last name (for individual).
account.beneficiaryEntityType	string	"individual" or "company".
account.currency	string	Target account currency.
account.status	string	Account status.

Example Payload

{
  "id": 10004,
  "amount": "1000.00",
  "reference": "REF-W2A-003",
  "state": "requested",
  "currency": "USD",
  "type": "wallet_to_account",
  "walletId": 4001,
  "createdDate": "2024-01-15T12:00:00Z",
  "account": {
    "id": 502,
    "accountNumber": "87654321",
    "bankName": "HSBC",
    "beneficiaryFirstName": "John",
    "beneficiaryLastName": "Smith",
    "beneficiaryEntityType": "individual",
    "currency": "USD",
    "status": "active"
  }
}

---

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 walletToAccount.requested
    if (event.state === 'requested') {
      console.log(`Processing Wallet to Account - Requested 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: