Withdrawal Webhook

HTTP Method: POST
Endpoint URL: https://your-server.com/webhooks/withdrawal (configured in your ALPPAY settings)
Description: ALPPAY sends this webhook to notify your server about withdrawal creation or status changes.
Security: Verify the X-HMAC header to ensure the request is from ALPPAY.

Webhook Configuration

To receive withdrawal webhooks:

1. Contact [email protected] with your webhook endpoint URL
2. Ensure your endpoint accepts POST requests
3. Implement HMAC signature verification for security
4. Respond with HTTP 200 OK to acknowledge receipt

Request Headers

• Content-Type: application/json
• X-HMAC: signature_string — HMAC-SHA256 signature of the request body

Request Body (JSON)

{
  "id": "5f5a8ced-5c6a-4038-9d73-662441242fd3",
  "txnId": "0xe7238caa68382485141be0443d6ba7efd0bd9f6bac5a624bd059acc53af1bf1d19",
  "amount": "10",
  "receivedAmount": "10",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "https://cryptologos.cc/logos/tether-usdt-logo.png",
    "network": "tron"
  },
  "addressFrom": "TXkFpL3HmzE9KPpXGWNXdCbNcDYYn73U4C",
  "addressTo": "TPSMckmxoQBQWfUcasbUs2cRUdh2EMQu4n",
  "destTag": "",
  "status": "COMPLETE",
  "customer": {
    "id": 1,
    "name": "Customer Name",
    "email": "[email protected]"
  },
  "merchant": {
    "id": 1,
    "name": "TestMerchant",
    "email": "[email protected]",
    "siteUrl": "",
    "logoUrl": ""
  },
  "invoice": "your-system-invoice-id",
  "createdAt": "2025-08-07T09:08:58.780375195Z",
  "updatedAt": "2025-08-07T10:15:32.123456789Z",
  "timeToApprove": "2025-08-07T10:08:58.780375195Z"
}

Field Descriptions

• id — Unique UUID of the withdrawal request
• txnId — Blockchain transaction ID (empty for OPEN status)
• amount — Requested withdrawal amount
• receivedAmount — Actually sent amount (0 for OPEN status)
• asset — Cryptocurrency details:
  • short — Ticker symbol (USDT, USDC)
  • name — Full name
  • logoUrl — Logo image URL
  • network — Blockchain network (tron, ethereum)
• addressFrom — Source wallet (empty for OPEN status)
• addressTo — Destination wallet address
• destTag — Destination tag/memo if applicable
• status — Current withdrawal status
• customer — Customer information from your system
• merchant — Your merchant account details
• invoice — Your internal reference ID
• createdAt — Withdrawal creation timestamp
• updatedAt — Last status change timestamp
• timeToApprove — Auto-approval timestamp (null if manual)

Webhook Events and Status Changes

ALPPAY sends webhooks for the following events:

1. Withdrawal Created (Status: OPEN)

Sent immediately after successful withdrawal creation via API.

2. Withdrawal Approved (Status: APPROVED)

Sent when withdrawal is approved (manually or automatically).

3. Withdrawal Completed (Status: COMPLETE)

Sent when withdrawal is successfully processed on blockchain.

• txnId will contain the blockchain transaction hash
• addressFrom will contain the source wallet address
• receivedAmount will match the amount

4. Withdrawal Cancelled (Status: CANCELLED)

Sent if withdrawal is cancelled before processing.

Required Response

Your server must respond with:

• HTTP Status: 200 OK
• Body: Empty or simple acknowledgment

Example successful response:

HTTP/1.1 200 OK
Content-Length: 0

HMAC Signature Verification

Always verify the webhook authenticity using the X-HMAC header:

Node.js Example

import crypto from 'crypto';

function verifyWebhook(body, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(body), 'utf8')
    .digest('hex');
  
  return signature === expectedSignature;
}

// In your webhook handler
app.post('/webhooks/withdrawal', (req, res) => {
  const signature = req.headers['x-hmac'];
  const isValid = verifyWebhook(req.body, signature, process.env.HMAC_SECRET);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the withdrawal update
  console.log('Withdrawal status:', req.body.status);
  
  res.status(200).send();
});

Retry Policy

If your server doesn't respond with 200 OK:

• ALPPAY will retry the webhook up to 5 times
• Retry intervals: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours
• After 5 failed attempts, the webhook is marked as failed

Best Practices

1. Always verify HMAC signature before processing
2. Respond quickly (within 5 seconds) to avoid timeouts
3. Use idempotent processing - same webhook may be sent multiple times
4. Log all webhooks for debugging and audit trails
5. Handle all status types even if you only care about specific ones
6. Store the withdrawal ID to match webhooks with your records

Testing Webhooks

For testing, you can:

1. Use services like ngrok to expose local endpoints
2. Create test withdrawals in sandbox environment
3. Monitor webhook logs in ALPPAY dashboard