Skip to content

Webhooks

Regini sends signed POST requests to your registered callback URL when key events occur on an account.

Registering your endpoint

Use the Regini partner portal to register your webhook URL and select which events to subscribe to.

You will receive a signing_secret once at registration. Store it securely — it is not shown again.

Supported events

Event When it fires
deposit.completed User confirmed the M-Pesa STK push and funds are credited
deposit.failed Deposit could not be credited (rare)
withdrawal.completed KES payout delivered to user's M-Pesa
withdrawal.failed Kotani payout failed or was cancelled

Payload

{
  "event": "deposit.completed",
  "account_id": "3f8a1b2c-...",
  "transaction_id": "tx-uuid-...",
  "amount_kes": 5000.0,
  "amount_usdc": 38.07,
  "exchange_rate": 131.35
}

Verifying the signature

Every webhook request includes two headers:

  • X-Regini-Signature: sha256=<hex>
  • X-Regini-Event: <event_name>

Always verify the signature before trusting the payload.

import hmac
import hashlib

def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

const crypto = require("crypto");

function verifyWebhook(secret, body, signature) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Responding

Return any 2xx status to acknowledge receipt. If your endpoint returns a non-2xx or times out (10 seconds), Regini retries with the following schedule:

Attempt Delay after previous failure
2 10 seconds
3 30 seconds
4 2 minutes
5 10 minutes
6 60 minutes

After 6 failed attempts (1 initial + 5 retries) the delivery is marked as failed. No further retries are made.

Info

Webhook delivery failures do not affect the underlying transaction. Funds are not reversed if a webhook cannot be delivered.