IZZIPAYDocumentation

Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur in your IZZIPAY account.

Webhook Setup

bash
curl -X POST https://api.izzipay.com/v1/developer/webhooks \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/izzipay",
    "events": ["payment.completed", "payment.failed"],
    "secret": "whsec_your_signing_secret"
  }'

Events

EventDescription
payment.completedPayment was successfully processed
payment.failedPayment attempt failed
payment.refundedPayment was refunded
wallet.creditedWallet received funds
wallet.debitedFunds were deducted from wallet
transfer.completedTransfer was completed
transfer.failedTransfer attempt failed
loan.disbursedLoan was disbursed to borrower
loan.repaymentLoan repayment received
kyc.verifiedKYC verification completed
kyc.rejectedKYC verification rejected
merchant.activatedMerchant account activated

Payload Format

json
{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "pay_xyz789",
    "amount": 5000,
    "currency": "USD",
    "status": "completed",
    "method": "mobile_money",
    "metadata": {}
  }
}

Signature Verification

Always verify webhook signatures to ensure the request is from IZZIPAY:

javascript
import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// In your webhook handler:
app.post('/webhooks/izzipay', (req, res) => {
  const signature = req.headers['x-izzipay-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    'whsec_your_signing_secret'
  );

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

  // Process the event
  const event = req.body;
  console.log(`Received: ${event.type}`);
  res.status(200).send('OK');
});

Best Practices

  • •Always return a 200 response quickly to avoid timeouts
  • •Process webhook payloads asynchronously
  • •Implement idempotency — you may receive the same event multiple times
  • •Use the event ID to deduplicate
  • •Verify signatures before processing any event