Optional verification helpers for inbound M-PESA webhook requests.

Safaricom Daraja callbacks are unsigned JSON POSTs. Authenticity must be enforced by the host application—typically via HTTPS, a shared secret embedded in the callback URL, IP allowlisting, idempotency on transaction IDs, and reconciliation against outbound API calls or Safaricom query/status APIs.

This module does not prove a payment occurred; it only helps reject requests that clearly did not come through your expected transport controls.

IP allowlist provenance

The built-in defaults are community-documented Safaricom Kenya callback egress addresses widely cited in M-Pesa integrator guides and open-source packages. They are not fetched from the live Daraja API and may change without notice.

Defaults combine:

• CIDR subnets 196.201.212.0/24, 196.201.213.0/24, and 196.201.214.0/24 (Safaricom 196.201.x.x address space)
• An explicit host list matching commonly published production callback IPs

Verify the current list with Safaricom support or your own production logs, then override via application config:

config :daraja,
  callback_cidrs: ["196.201.214.0/24", "196.201.213.0/24", "196.201.212.0/24"],
  callback_hosts: ["196.201.214.200", "196.201.212.127"]

Per-request overrides are also supported through verify/1 and safaricom_ip?/2.

IP allowlisting is intended for production. Sandbox callbacks (for example via ngrok) typically will not match these ranges—disable check_ip in dev.

Example (Phoenix)

with :ok <-
       Daraja.Callback.Security.verify(
         ip: conn.remote_ip,
         check_ip: true,
         shared_secret: Application.fetch_env!(:my_app, :mpesa_callback_secret),
         provided_secret: conn.params["token"]
       ),
     {:ok, callback} <- Daraja.Express.Callback.parse(payload),
     :ok <- Daraja.Callback.Guard.ensure_fresh(callback.checkout_request_id) do
  # ...fulfil order...
  json(conn, Daraja.Express.Callback.accept())
else
  {:error, :untrusted_ip} -> send_resp(conn, 403, "Forbidden")
  {:error, :invalid_secret} -> send_resp(conn, 403, "Forbidden")
  {:error, :invalid_callback, _} -> send_resp(conn, 400, "Bad Request")
  {:error, :duplicate} -> json(conn, Daraja.Express.Callback.accept())
end

Register callback URLs with a secret query parameter, for example https://example.com/mpesa/callback?token=your-secret, and pass the same value to provided_secret.