Webhooks

Inshuwa sends webhook notifications to your server when payment and policy events occur.

Overview

Webhooks allow you to receive real-time updates instead of polling the API. When an event occurs (such as a successful payment), Inshuwa sends an HTTP POST request to your configured webhook URL.

Setup

Configure your webhook URL in the Inshuwa dashboard under Settings > Webhooks.

Your webhook endpoint must:

• Accept POST requests
• Return a 200 OK status code
• Be publicly accessible over HTTPS

Payment Webhook

Inshuwa sends a payment notification to your webhook URL when a policy payment is processed.

Example payload:

{
  "policyId": "pol_abc123",
  "paymentReference": "PAY-20240101-001",
  "partnerReference": "your-unique-reference-123",
  "status": "Success",
  "amount": 1500.00,
  "currency": "ZMW",
  "policyNumber": "MOT-2024-00001",
  "policyStatus": "Active",
  "paidAt": "2024-01-01T10:30:00Z"
}

Webhook Fields

Field	Type	Description
policyId	string	Inshuwa internal policy ID
paymentReference	string	Inshuwa payment reference
partnerReference	string	Your reference from the payment request
status	string	Payment status: Success, Failed, Pending
amount	number	Amount paid
currency	string	Currency code (e.g., ZMW)
policyNumber	string	Human-readable policy number
policyStatus	string	Current policy status after payment
paidAt	string	ISO 8601 timestamp of payment

Verifying Webhooks

Always verify that webhook requests originate from Inshuwa. Check with your account manager for webhook signing details.

Example Handler (Node.js)

app.post('/webhooks/inshuwa/payment', (req, res) => {
  const { policyId, partnerReference, status, amount } = req.body;

  if (status === 'Success') {
    // Update your database, send confirmation email, etc.
    console.log(`Policy ${policyId} paid. Amount: ${amount}`);
  }

  // Always respond with 200
  res.status(200).send('OK');
});

Retry Policy

If your webhook endpoint is unavailable or returns a non-2xx status, Inshuwa will retry the delivery with exponential backoff. Ensure your endpoint is idempotent — the same webhook may be delivered more than once.