Webhooks

Webhooks let your systems react to MFI events in real time instead of polling. Configure subscribers per event type with retry policies and verify signatures with a shared secret.

Event catalogue

Event envelope

{
  "id": "evt_01HXY9TZQ7K2P8",
  "event": "loan.disbursed",
  "created": "2026-03-15T10:42:17.182Z",
  "tenant": "microfinance.mybridgeerp.com",
  "api_version": "v1",
  "data": {
    "loan": {
      "id": 9183,
      "loan_no": "L-2026-09183",
      "member_id": 4827,
      "member_name": "Jane Wambui Mwangi",
      "principal": 5000000,
      "state": "active"
    },
    "disbursement": {
      "id": 7211,
      "amount": 5000000,
      "channel": "mpesa_b2c",
      "provider_ref": "PBJ4S6X9DC",
      "posted_at": "2026-03-15T10:42:15Z"
    }
  }
}

Verifying the signature

Every webhook POST carries an X-MFI-Signature header containing an HMAC-SHA256 hex digest of the raw request body, computed with the subscriber secret. Always verify before processing.

import hmac, hashlib

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

# Flask example
@app.post('/mfi-webhook')
def receive():
    sig = request.headers.get('X-MFI-Signature', '')
    if not verify(SECRET, request.data, sig):
        abort(401)
    event = request.json
    process(event)
    return '', 200

Delivery and retry

1. First attempt fires immediately after the source action commits
2. If subscriber returns non-2xx or times out (default 10s), event queued for retry
3. Retry attempt 1 after 1 minute
4. Retry attempt 2 after 5 minutes
5. Retry attempt 3 after 30 minutes
6. After 3 failed retries, event moves to dead letter queue in Settings > API > Webhooks > Failed

Configuring a subscriber

Settings > Technical > Webhooks > Create.

• Name — human label
• URL — HTTPS endpoint
• Secret — generated once, never shown again
• Events — multi-select event types to subscribe to
• Active — toggle to disable without deleting
• Headers — optional custom headers (e.g. Authorization)

Worked scenarios

Reference

Webhook request headers

Troubleshooting

See also

• Api
• Rest
• Openapi