Webhooks

Receive real-time notifications when payment events occur. Webhooks allow your application to react instantly to completed payments without polling.

---

Overview

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│    Customer     │         │    MakaPay      │         │   Your Server   │
│                 │         │                 │         │                 │
│  Sends payment  │ ──────→ │  Processes      │         │                 │
│                 │         │  payment        │         │                 │
│                 │         │       ↓         │         │                 │
│                 │         │  Sends webhook  │ ──────→ │  Receives POST  │
│                 │         │                 │         │  request        │
│                 │         │                 │         │       ↓         │
│                 │         │                 │         │  Fulfills order │
└─────────────────┘         └─────────────────┘         └─────────────────┘

---

Setup

Prerequisites

• An active API key (required for webhook authentication)

• An HTTPS endpoint on your server

Configure Webhook URL

1. Go to Dashboard → Webhooks

2. Enter your webhook URL (must be HTTPS)

3. Toggle Active to enable

4. Click Save

Generate API Key

If you don't have an API key:

1. Go to Dashboard → API Keys

2. Click Create New Key

3. Save the key securely

---

Webhook Events

payment.completed

Sent when a payment is successfully settled to your wallet.

{
  "event": "payment.completed",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "orderId": "order-12345",
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "recipientAddress": "0xabc123...",
  "amount": "100.00",
  "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
  "chainId": 137,
  "description": "Premium subscription",
  "status": "completed",
  "transactionHash": "0x...",
  "overpayment": "0.00",
  "feeDetails": {
    "gasUsed": 145000,
    "gasPrice": "30000000000",
    "usdtAmountUsed": "1.13",
    "planTier": "free"
  },
  "timestamp": 1704067200000
}

payment.withdrawn

Sent when a partial payment is manually withdrawn.

{
  "event": "payment.withdrawn",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "orderId": "order-12345",
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "recipientAddress": "0xabc123...",
  "amount": "100.00",
  "amountWithdrawn": "75.00",
  "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
  "chainId": 137,
  "status": "withdrawn",
  "withdrawalTransactionHash": "0x...",
  "timestamp": 1704067200000
}

payment.awaiting_gas

Sent when payment is received but Gas Tank balance is insufficient. Informational only - no retry on this event.

{
  "event": "payment.awaiting_gas",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "orderId": "order-12345",
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "amount": "100.00",
  "status": "awaiting_gas",
  "estimatedFeeUsdt": "1.13",
  "gasTankBalance": "0.50",
  "requiredTopUp": "0.63",
  "timestamp": 1704067200000
}

---

Webhook Security

Signature Verification

Every webhook includes a signature header for verification:

X-Signature: sha256=a1b2c3d4e5f6...

Verifying the Signature

const crypto = require('crypto');

function verifyWebhook(payload, signature, apiKey) {
  const expectedSignature = crypto
    .createHmac('sha256', apiKey)
    .update(JSON.stringify(payload))
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const isValid = verifyWebhook(req.body, signature, YOUR_API_KEY);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

Python Example

import hmac
import hashlib
import json

def verify_webhook(payload, signature, api_key):
    expected = hmac.new(
        api_key.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()

    return f"sha256={expected}" == signature

---

Retry Policy

Failed webhook deliveries are automatically retried:

Attempt	Delay
1st	Immediate
2nd	5 minutes
3rd	10 minutes

What Counts as Failure

• HTTP status code outside 200-299

• Connection timeout (30 seconds)

• SSL/TLS errors

• DNS resolution failure

After All Retries Fail

• Webhook is marked as failed

• No further automatic retries

• You can manually retry from the dashboard

---

Best Practices

1. Respond Quickly

Return a 200 response as fast as possible. Do heavy processing asynchronously.

app.post('/webhook', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  processPayment(req.body).catch(console.error);
});

2. Implement Idempotency

Webhooks may be delivered more than once. Use paymentId to prevent duplicate processing.

async function processPayment(webhook) {
  const exists = await db.payments.findOne({
    paymentId: webhook.paymentId
  });

  if (exists) {
    console.log('Already processed, skipping');
    return;
  }

  // Process payment...
  await db.payments.insert({ paymentId: webhook.paymentId, ... });
}

3. Verify Signatures

Always verify the X-Signature header before processing.

4. Use HTTPS

Webhook URLs must use HTTPS. HTTP endpoints are rejected.

5. Handle All Event Types

Your endpoint should gracefully handle unknown event types:

switch (webhook.event) {
  case 'payment.completed':
    handleCompleted(webhook);
    break;
  case 'payment.withdrawn':
    handleWithdrawn(webhook);
    break;
  default:
    console.log('Unknown event type:', webhook.event);
}

---

Testing Webhooks

Manual Trigger

1. Go to Dashboard → Payments

2. Click on a completed payment

3. Click Resend Webhook

4. Check your webhook logs

Webhook Logs

View delivery history in Dashboard → Webhooks → Logs:

Column	Description
Payment ID	Associated payment
Status	success / failed / pending
Status Code	HTTP response code
Attempts	Delivery attempts made
Response	Server response (truncated)

Local Testing

Use a tunnel service like ngrok for local development:

ngrok http 3000
# Use the https URL as your webhook endpoint

---

Payload Reference

Common Fields

Field	Type	Description
event	string	Event type
paymentId	string	Unique payment identifier
orderId	string	Your order reference
merchant	string	Merchant wallet address
recipientAddress	string	Payment address
amount	string	Payment amount
token	string	Token contract address
chainId	number	Blockchain network ID
status	string	Payment status
timestamp	number	Unix timestamp (ms)

Optional Fields

Field	Type	When Present
description	string	If provided at creation
transactionHash	string	On completed payments
withdrawalTransactionHash	string	On withdrawals
amountWithdrawn	string	On partial withdrawals
overpayment	string	If customer overpaid
feeDetails	object	On completed payments
blockConfirmations	number	If confirmations required

---

Troubleshooting

Webhook Not Received

1. Check webhook is Active in dashboard

2. Verify URL is correct and uses HTTPS

3. Check your server logs for incoming requests

4. Review webhook logs for delivery status

Signature Mismatch

1. Ensure you're using the correct API key

2. Verify you're hashing the raw JSON payload

3. Check for encoding issues (UTF-8)

Timeouts

1. Respond with 200 before processing

2. Move heavy operations to background jobs

3. Increase server timeout if needed

Duplicate Events

1. Implement idempotency using paymentId

2. Check webhook logs for retry attempts

3. Review your response codes (non-2xx triggers retry)