Bank webhooks and operational monitoring

A bank webhook provider defines how Makronexus receives and normalizes server-to-server messages from a bank, mobile-money service or payment gateway. A webhook event records one received provider message, its event type, processing status, external reference, financial fields, matching fields, raw payload, normalized data, error detail and processing timestamps.

Webhook operations are integration evidence. A completed webhook does not by itself prove that a Payment was saved, allocated, receipted, posted, reconciled or settled. Provider configuration and operational event monitoring must therefore be linked to the P4 Payment lifecycle and P6 reconciliation controls.

Audience: payment operations staff, finance administrators, implementers, support analysts, security teams, accountants and auditors
Learning time: 55 minutes
Navigation: Finance → Bank webhooks (finance/bank-webhooks)
Control objective: receive provider events securely, process them idempotently, identify duplicates/failures quickly and retain enough evidence to reproduce every financial effect.

Learning outcomes

You will be able to:

• distinguish provider configuration from event evidence;
• explain the verified provider and event types;
• identify exact webhook permissions and current frontend-gate caveats;
• protect HMAC/API secrets and callback configuration;
• interpret received, processing, completed, failed, duplicate and ignored events;
• trace a webhook to a Payment Attempt, Payment and reconciliation item;
• investigate duplicate, failed and unmatched events;
• define daily monitoring and escalation routines;
• prove that autoReconcile is configuration, not proof of reconciliation.

Exact definition and boundaries

Object or flag	Meaning	Boundary
Webhook provider	school-scoped adapter configuration	not a provider settlement account
Provider code	stable adapter/provider identity	not a merchant payout ID
Field mapping	source payload key to normalized field mapping	not a guarantee the source schema is unchanged
HMAC/API secret	authentication/verification material	must never be displayed or copied into documentation
Callback URL	endpoint provider calls	not proof events are arriving
isActive	configuration is enabled	not proof provider credentials work
autoReconcile	provider configuration permits automated downstream behavior	not proof an event was correctly matched/reconciled
Webhook event	retained received/processed message	not automatically a Payment
Raw payload	original provider message	sensitive evidence requiring controlled access
Normalized data	mapped fields used by Makronexus	must remain traceable to raw payload
Statistics	aggregate event counts and amounts	not transaction-level reconciliation evidence

Verified provider types are bank, mobile_money and payment_gateway. Built-in provider codes include generic-bank, ecocash, onemoney and telecash; other channel workspaces may use additional gateway configurations through the unified Payment Attempt layer.

Provider model

Provider configuration fields

Field	Meaning	Control
Provider code	stable integration identifier	do not change casually after events exist
Provider name	operator-facing label	include bank/channel and merchant scope
Provider type	bank, mobile money or gateway	must match integration design
School	owner scope	never reuse across schools without supported design
Active flag	accepts/uses provider configuration	disable through controlled change
Field mapping	source-to-normalized keys	version/test when source schema changes
Config	credentials, signature and callback settings	secrets must be masked and access-restricted
Auto reconcile	downstream automation preference	test and monitor; never treat as evidence
Default currency	fallback provider currency	explicit event currency still requires validation
Webhook URL	callback endpoint	confirm provider registration and environment
Last event / total events	operational health indicators	absence/presence requires context

The config contract may include API key, API secret, HMAC secret/header, signature algorithm, callback URL and metadata. Operational documentation must refer to secret names, not secret values.

Roles and exact permissions

Action	Exact API ability	Control
Create provider	bank_webhook:create	configuration maker
Read provider or event	bank_webhook:read	sensitive evidence access
Update provider	bank_webhook:update	test and approval required
Delete provider	bank_webhook:delete	preserve event/audit retention
List providers/events	bank_webhook:list	daily monitoring
View statistics	bank_webhook:statistics	aggregate operations
Server callback	bank_webhook:callback	service-to-service, not normal frontend use
Create Payment Attempt	payment_attempt:create	customer/channel initiation
Read attempt	payment_attempt:read	trace callback lineage
List attempts	payment_attempt:list	search duplicates/failures
Confirm attempt	payment_attempt:confirm	exceptional administrative action
Cancel attempt	payment_attempt:cancel	does not refund/settle
List reconciliation items	reconciliation_item:list	inspect downstream state
Resolve discrepancies	reconciliation:resolve_discrepancy	evidence and notes required

The current Bank Webhooks page uses legacy/generic frontend gates based on financial_payment/payments capabilities for visibility and provider mutations, while the API guide defines exact bank_webhook:* permissions. Treat both layers seriously: page visibility is not proof the API request will succeed, and a legacy gate should not be documented as a universal webhook authority.

Event types and processing statuses

Verified event types:

Event type	Typical meaning	Required investigation
transaction.received	provider reports an incoming transaction	link to attempt/Payment and later settlement
transaction.reversed	provider reports reversal	trace original and correction effects
transaction.failed	provider reports unsuccessful transaction	ensure no Payment/economic effect exists
notification	non-transaction provider message	inspect normalized purpose; do not assume money movement

Verified processing statuses:

completed describes webhook processing. It does not guarantee the provider transaction is final or that every downstream record exists.

Secure callback sequence

Never reveal whether a secret value was correct in user-facing errors. Retain request IDs and provider event IDs for support.

Prerequisites

Requirement	Why it matters
Approved provider and merchant agreement	defines sender and event semantics
Correct tenant/school configuration	prevents cross-school financial effects
Production callback URL registered	events must reach the correct environment
Signature/HMAC design and secret rotation process	verifies origin and integrity
Field mapping tested with signed fixtures	normalized values must be reproducible
Idempotency/external event identity	protects against retries and duplicates
Payment Attempt integration	callback must link to the owning attempt
Monitoring owner and escalation route	failures require timely action
Reconciliation process	completed events still need financial comparison
Security-controlled raw payload access	payloads may contain personal/financial data

Configure a provider safely

1. Define scope

Record provider code, merchant account, school, provider type, default currency, supported event types and environment.

2. Create credentials outside documentation

Generate or receive API/HMAC credentials through the approved secret-management process. Do not store secrets in tickets, screenshots, spreadsheets or documentation.

3. Configure field mappings

Map provider fields for external reference, amount, currency, sender/payer identity, student reference, invoice reference, event type and status where supported.

Expected result: a signed test fixture produces the expected normalized data.

4. Configure callback and signature verification

Register the exact callback URL with the provider. Confirm required signature header and algorithm.

Expected result: invalid signatures are rejected and valid signed fixtures are accepted.

5. Set activation and automation deliberately

Enable the provider only after end-to-end testing. Set autoReconcile only if the approved workflow and monitoring can support it.

Control: automation must not bypass Payment, matching, review or accounting controls.

6. Complete negative tests

Test:

• invalid signature;
• missing signature;
• wrong school/provider;
• duplicate event ID;
• changed amount on repeated ID;
• unsupported event type;
• malformed currency/amount/date;
• delayed event;
• reversal after success;
• provider timeout/retry.

Daily monitoring workflow

Recommended daily questions:

1. Did every active provider send events within the expected operating window?
2. Are any events stuck in received or processing?
3. Are failed events increasing by provider or event type?
4. Are duplicates normal retries or conflicting payloads?
5. Are ignored events understood?
6. Do completed transaction events link to Attempts and Payments?
7. Do provider totals agree with the frozen reconciliation population?
8. Are reversals/failed events reflected in correction workflows?
9. Are secrets, callback URLs or field mappings near a planned change?
10. Are unresolved blocking exceptions assigned?

Event investigation procedure

1. Freeze identifiers

Record event ID, provider ID/code, external reference, event type, status, amount, currency, school, created time and request ID.

2. Compare raw and normalized evidence

Inspect raw payload under controlled access. Compare each normalized financial and matching field to its source key and mapping.

3. Verify signature/identity evidence

Use server logs or security evidence; do not expose secrets. Confirm event identity and duplicate rules.

4. Trace downstream lineage

Search Payment Attempts using provider/external reference. Confirm attempt status and linked Payment ID. Inspect Payment amount/currency and downstream reconciliation item.

5. Classify the event

• processing delay;
• handler/service error;
• duplicate retry;
• conflicting duplicate;
• unsupported notification;
• provider reversal/failure;
• missing Payment;
• wrong school or merchant;
• mapping/data-quality defect.

6. Recover idempotently

Retry processing only through the supported operation or service path using the same external/idempotency identity. Do not manually create duplicate Payments.

7. Reconcile and close

Ensure the corrected event is reflected in provider and bank reconciliation. Record action, actor, timestamp and result.

Statistics and alerting

Provider statistics include total events, completed events, failed events, duplicate events, total amount, currency and last event time. Useful indicators include:

Indicator	Possible issue	Required drill-down
No recent events	provider/callback outage or no activity	provider health and expected volume
Rising failed rate	schema, credentials or worker failure	event errors and deployment changes
Rising duplicates	provider retry storm or slow acknowledgements	external IDs and payload equality
Amount spike	true volume or mapping/decimal error	transaction-level events
Completed without Payment	downstream handler gap	attempt and Payment lineage
Reversal spike	provider or fraud/chargeback activity	original events and corrections

Do not convert a statistic into a financial conclusion without transaction-level evidence.

Change and secret rotation control

When changing provider configuration:

1. capture the current configuration fingerprint without exposing secrets;
2. approve the change and maintenance window;
3. retain old/new mapping versions;
4. rotate credentials through secret management;
5. coordinate provider callback changes;
6. run positive and negative signed fixtures;
7. monitor both old and new event flows where overlap is required;
8. confirm no event loss or duplicate economic effect;
9. record rollback criteria;
10. complete reconciliation after the change.

Worked scenario: Mupfure Learning Academy

Mupfure’s mobile-money events normally arrive every few minutes. The dashboard shows 60 failed events after the provider added a nested transaction.amount field and stopped sending the previous top-level amount.

The events are signed correctly and retained as failed. The support analyst compares raw and normalized payloads and confirms the mapping defect. No second provider configuration is created. An authorised administrator updates the field mapping under bank_webhook:update, tests signed fixtures, and reprocesses events through the supported idempotent path.

Fifty-eight events link to existing processing attempts and create/link Payments exactly once. Two events are duplicates with identical external IDs and payloads; they remain duplicate. The team reconciles the recovered population to the provider report and bank payout before closing the incident.

Failure modes

Symptom	Likely cause	Evidence to inspect	Safe action	Escalate when
Provider has no recent events	callback, credentials, provider outage or no activity	last event time, provider health, logs	test without changing financial data	active payments exist but no callback evidence
Events stuck processing	worker/queue failure	event age, request/job IDs	recover through supported worker path	backlog threatens settlement/close
Failed events share one field error	provider schema changed	raw payload and mapping	version/test mapping update	prior completed events may be wrong
Duplicate events have different amounts	provider reused ID or tampering/data defect	signatures and raw payload hashes	quarantine; do not choose one silently	economic effects already exist
Completed event has no Payment	downstream confirmation failure	attempt/provider IDs and audit	idempotent recovery	no safe automated recovery
Event linked to wrong school	merchant/provider scope defect	provider config and payload identifiers	stop provider and contain effects	cross-school data/economic effects occurred
Reversal event ignored	unsupported mapping or workflow gap	event type and original Payment	create controlled correction	statement/provider evidence diverges
Auto reconcile appears successful but batch differs	automation is incomplete or thresholds wrong	reconciliation items and config	treat as exception and review	batch/period was closed
Secret shown in UI/log	masking or logging defect	access logs and screenshots	rotate secret and contain access	production credential exposure
Delete provider would remove context	destructive configuration action	event history/retention policy	disable and retain where required	API delete conflicts with audit policy

Verification checklist

• Provider code, type, school, merchant scope and currency are approved.
• Callback URL points to the intended environment.
• Secrets are stored and rotated securely.
• Signature and negative tests pass.
• Field mappings are versioned and tested.
• Duplicate identity behavior is verified.
• Active and auto-reconcile flags are deliberate.
• Event statuses are monitored daily.
• Failed, duplicate and ignored events are understood.
• High-value completed events trace to attempts and Payments.
• Reversal/failure events trace to correction workflows.
• Provider event totals reconcile to provider reports and batches.
• Bank payout evidence is separately reconciled.
• Configuration changes include rollback and post-change reconciliation.
• Raw payload access and retention are controlled.

Practice and knowledge check

Guided practice: use signed fixtures for one successful event, one invalid signature, one duplicate, one changed-payload duplicate and one reversal. Prove the expected status and downstream effect of each.

Independent scenario: statistics show 100 completed events and USD 10,000 processed, but the provider report contains USD 9,700 and the bank received USD 9,500. Build the investigation sequence.

1. What does completed mean?
2. Why is autoReconcile not proof?
3. Which permissions govern provider CRUD and event access?
4. Why must raw and normalized data both be retained?
5. What is the correct response to a duplicate with different payload data?
6. Why should failed events not be repaired by manually creating Payments?
7. What should daily monitoring cover?
8. Why must provider statistics be reconciled to report and bank evidence?
9. What must happen after a field-mapping change?

Answer guide: completed means event processing succeeded; automation still requires result verification; use bank_webhook:create/read/update/delete/list/statistics; raw data proves source and normalized data proves interpretation; conflicting duplicates must be quarantined; manual Payment creation risks duplication; monitor freshness/backlogs/failures/duplicates/lineage/totals/exceptions; statistics are aggregates, not settlement; test, reprocess idempotently, reconcile and retain change evidence.

P6 completion gate

P6 is complete when an independent reviewer can:

• reproduce a bank import from retained provenance;
• reconcile every source row and control total;
• match external lines to correct Payments;
• explain all residual items and amounts;
• reconcile provider gross activity to net payout and bank credit;
• prove webhook event lineage and duplicate handling;
• operate continuous exception ownership, escalation and certification;
• identify unresolved external, accounting and period-close handoffs without hiding them.

Next phase

Continue to P7 when published for dashboards, revenue and collection reporting, receivables/ageing, cash-flow forecasting, accounting/statutory reporting, evidence exports and multi-currency/consolidated reporting.