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

Checking What Was Delivered

Every delivery attempt against a transaction is logged. When a webhook did not arrive, read the log before assuming it was never sent — it records the attempts, the status we got back, and the retries.

Your API key

Set it once and every Try it out below is authenticated. It stays in this browser's local storage and is never sent anywhere but the API.

Callback delivery log for a transaction

Reference →

GET/payments/transactions/{reference}/callbacks

Playground

Authorization

BearerAuth

Variables

Key

Value

reference*

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.