ERP Accounting Bridge & Cryptographic Webhooks Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Double-Entry Accounting Engine
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The ERP Accounting Bridge & Cryptographic Webhooks module (public.accounting_mappings, public.webhook_endpoints, and public.webhook_logs) bridges the operational telecom revenue engine of Ring2All Billing with institutional Enterprise Resource Planning (ERP) accounting platforms (such as QuickBooks Online, Xero, Odoo, SAP, and NetSuite).

Core Components & Subsystems

1. Chart of Accounts Mapping (public.accounting_mappings): Maps internal billing transaction categories directly to standard general ledger account codes (Assets, Liabilities, Equity, Revenue, COGS, and Expenses).
2. Double-Entry General Journal Export: Generates balanced debit and credit journal entry exports adhering to standard GAAP and IFRS accrual accounting principles.
3. Cryptographic Webhooks Engine (public.webhook_endpoints): Dispatches real-time HTTPS webhooks signed with HMAC-SHA256 cryptographic signatures to external ERP listeners upon key financial events.

-- Chart of Accounts Mapping Schema
CREATE TABLE public.accounting_mappings (
    id BIGSERIAL PRIMARY KEY,
    category VARCHAR(50) NOT NULL UNIQUE,
    account_code VARCHAR(50) NOT NULL,
    account_name VARCHAR(100) NOT NULL,
    description TEXT,
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Cryptographic Webhooks Schema
CREATE TABLE public.webhook_endpoints (
    id BIGSERIAL PRIMARY KEY,
    uuid UUID NOT NULL DEFAULT gen_random_uuid(),
    url VARCHAR(255) NOT NULL,
    secret VARCHAR(100) NOT NULL,
    events TEXT[] NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Cryptographic Webhook Security Specification

All outbound HTTP POST payloads include an HMAC-SHA256 signature in the HTTP header:

POST /api/billing/webhook HTTP/1.1
Host: erp.acmetelecom.com
Content-Type: application/json
X-Ring2All-Signature: sha256=4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a
X-Ring2All-Event: invoice.paid
X-Ring2All-Timestamp: 1788806400

External ERP receivers verify message integrity and authenticity by computing hmac_sha256(payload, webhook_secret).

---

2. Module Overview (Commercial & Business Value)

• Elimination of Double-Entry Bookkeeping: Automatically translates thousands of metered telecom micro-transactions into summarized, balanced General Journal entries, eliminating human bookkeeping errors.
• Instant Financial Closing: Enables financial controllers to close monthly books in minutes rather than weeks through one-click CSV journal export and live webhook reconciliation.
• Zero-Trust Enterprise Security: Cryptographic HMAC-SHA256 request signing ensures that external accounting systems only process legitimate, unaltered financial transactions originating from the authenticated billing platform.
• Real-Time Event Notification: Financial webhooks allow downstream CRM, ERP, and payment management software to respond immediately when payments clear or accounts fall into delinquency.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control & Webhook Secret Management	Configures ERP endpoints, manages HMAC signing secrets, and configures automated retry policies.
Chief Financial Officer / Lead Accountant	Chart of Accounts & Journal Export	Configures general ledger account codes, audits balanced debit/credit reconciliations, and downloads monthly ERP journal exports.
Integration Engineer	Webhook Debugging & Payload Inspection	Inspects HTTP response statuses in the delivery log, diagnoses endpoint timeouts, and verifies payload schema structures.
Financial Auditor	Read-Only Ledger Verification	Inspects audit trails, verified delivery timestamps, and general ledger journal accuracy.

---

4. Visual Interface & Form Structure

4.1 Chart of Accounts Configuration (Tab 1)

The Chart of Accounts tab allows accountants to map platform revenue streams, carrier costs, and sales tax liabilities to their corporate ERP ledger codes.

4.2 Cryptographic Webhooks & Delivery Logs (Tab 2)

The Webhooks tab manages active HTTPS webhook endpoints, secret keys, subscribed events, and an interactive real-time inspection log tracking HTTP response codes and retry counts.

4.3 General Journal CSV Export Modal

Operators can export balanced general ledger journal entries for any historical date range, configured specifically for import into QuickBooks, Xero, Odoo, or SAP.

4.4 Default Chart of Accounts Categories

Financial Category	Default Account Code	Default Account Name	Normal Balance	Description
voice_revenue	4000	Voice Usage Revenue	Credit	Metered outbound and inbound voice call usage revenue from rated CDRs.
subscription_revenue	4100	Plan Subscription Revenue	Credit	Recurring monthly subscription fees billed for hosted PBX and trunk plans.
did_revenue	4200	DID & Number Revenue	Credit	Recurring and setup fees collected for wholesale and retail DID numbers.
sales_tax_payable	2100	Sales & Telecom Tax Payable	Credit	Collected municipal, state, and federal telecom taxes and regulatory fees.
carrier_cogs	5000	Carrier Termination COGS	Debit	Direct wholesale costs incurred from terminating carrier providers.
customer_wallet_liability	2200	Customer Prepaid Liability	Credit	Unearned customer prepaid deposits held in wallets prior to usage.

---

5. Architectural Flow & Double-Entry Accounting Engine

 ┌────────────────────────────────────────────────────────────────────────┐
 │                   Billing Event (e.g. Invoice Finalized)               │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
            ┌────────────────────────┴────────────────────────┐
            │                                                 │
            ▼ (Batch General Journal)                         ▼ (Real-Time Webhook)
 ┌───────────────────────────────────────┐         ┌───────────────────────────────────────┐
 │   Double-Entry Ledger Balancing       │         │   Cryptographic Signing Engine        │
 │  • Debit: Accounts Receivable (1200)  │         │  • Generate payload JSON string       │
 │  • Credit: Voice Revenue (4000)       │         │  • Compute HMAC-SHA256 with secret    │
 │  • Credit: Sales Tax Payable (2100)   │         │  • Set `X-Ring2All-Signature` header  │
 └──────────────────┬────────────────────┘         └──────────────────┬────────────────────┘
                    │                                                 │
                    ▼                                                 ▼
 ┌───────────────────────────────────────┐         ┌───────────────────────────────────────┐
 │   Export Balanced Journal CSV         │         │   HTTPS POST to External ERP Listener │
 │  • Compatible with QuickBooks / Odoo  │         │  • Log HTTP response status in DB     │
 └───────────────────────────────────────┘         └───────────────────────────────────────┘

---

6. Common Scenarios & Operational Playbooks

Scenario A: Adding an Odoo ERP Webhook Listener

1. Navigate to REPORTS / Financial Reports / Account Bridge.
2. Select the Cryptographic Webhooks tab.
3. Click Add Webhook Endpoint.
4. Enter your ERP listener URL (e.g. https://erp.yourcompany.com/api/v1/billing/webhook).
5. Select target events: invoice.created, invoice.paid, and customer.balance_depleted.
6. Copy the generated HMAC secret key into your ERP webhook signature verifier and click Save Endpoint.

Scenario B: Exporting Monthly Journal Entries for Financial Closing

1. In the Account Bridge module, click Export Journal CSV in the top action toolbar.
2. Select the Period Start and Period End dates (e.g., first and last day of the target month).
3. Click Download Journal CSV. The system generates a balanced double-entry spreadsheet where Total Debits equal Total Credits.

---

7. Troubleshooting & Diagnostic Commands

Inspect Failed Webhook Delivery Logs

SELECT l.id, e.url, l.event_type, l.response_status, l.attempts, l.created_at
FROM webhook_logs l
JOIN webhook_endpoints e ON e.id = l.endpoint_id
WHERE l.response_status IS NULL OR l.response_status >= 400
ORDER BY l.created_at DESC
LIMIT 10;

Verify Chart of Accounts Completeness

SELECT category, account_code, account_name
FROM accounting_mappings
ORDER BY account_code ASC;

---

8. Model Context Protocol (MCP) AI Integration

The ERP Accounting Bridge & Cryptographic Webhooks module connects directly to the Ring2All BSS MCP Server, enabling financial copilots and accounting auditors to inspect chart of accounts mappings and retrieve summarized double-entry ledger totals.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
get_accounting_journal_summary	Billing Operations / Admin	Retrieves summary of double-entry general ledger journal entries and mapped accounts for finance reconciliation.	{"startDate": "2026-09-01", "endDate": "2026-09-30"}

Sample MCP Tool Execution: get_accounting_journal_summary

Request Payload

{
  "name": "get_accounting_journal_summary",
  "arguments": {
    "startDate": "2026-09-01",
    "endDate": "2026-09-30"
  }
}

Response Payload

{
  "period": {
    "startDate": "2026-09-01",
    "endDate": "2026-09-30"
  },
  "totalDebits": 14520.80,
  "totalCredits": 14520.80,
  "isBalanced": true,
  "mappedAccountsCount": 8,
  "mappings": [
    {
      "category": "voice_usage_revenue",
      "accountCode": "4000",
      "accountName": "Voice Usage Revenue"
    },
    {
      "category": "carrier_cogs",
      "accountCode": "5000",
      "accountName": "Carrier Termination Expense"
    }
  ]
}

Conversational AI Prompts for Copilot

• “Provide the accounting journal summary and trial balance for September 2026.”
• “Are all revenue and expense categories mapped to active General Ledger accounts?”
• “Verify if total debits match total credits for the current billing cycle.”

---

9. Glossary

• Account Bridge: The integration layer linking telecom rating transactions to institutional accounting general ledgers.
• COGS (Cost of Goods Sold): Direct variable wholesale carrier fees incurred in delivering telephony minutes.
• Double-Entry Bookkeeping: Accounting standard requiring every transaction to record equal and offsetting debit and credit entries.
• HMAC-SHA256: Keyed-hash message authentication code ensuring payload integrity and origin authenticity.
• Webhook: An automated HTTP callback triggered by an event in Ring2All Billing and dispatched to an external server.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.