Skip to main content

Webhooks

Cortex sends enrichment and decision results to the webhook URL configured for your integration. Your endpoint should accept POST requests and process the event indicated by the event field.

Respond with a 2xx status as soon as the payload is received. The response confirms receipt; process the payload asynchronously after acknowledging it.

Webhook structure​

Every Cortex webhook contains:

FieldTypeDescription
eventstringThe event that determines the structure of data.
dataobjectThe enrichment or decision response for the assessment.

Supported events​

The decisioning-engine event contains the final recommendation, TrustScore, payment assessments, risk factors, explanation, and decision metadata.

Sample decisioning-engine webhook
{
  "event": "decisioning-engine",
  "data": {
    "metadata": {
      "assessment_id": "assessment_sample_001",
      "business_id": "business_sample_001",
      "bvn": "00000000000"
    },
    "decision": {
      "recommendation": "decline",
      "approved_amount": 0,
      "confidence": "high",
      "conditions": {
        "interest_rate": null,
        "tenor_days": null,
        "repayment_frequency": null,
        "covenants": [],
        "special_conditions": [
          "Automatic decline due to TrustScore alerts (Overdue days exceed 180)"
        ]
      }
    },
    "trust_score": {
      "score": 395,
      "recommendation": "DECLINE",
      "breakdown": {
        "trust_score": 395,
        "risk_band": "High Risk",
        "raw_achieved": 95.39,
        "raw_max": 550,
        "category_breakdown": {
          "Personal Details": 49.91,
          "Policy Norms": 0,
          "Financial Analysis": 33.05,
          "Credit History": 12.43
        },
        "reasons": [
          "Age: +40",
          "Educational Qualification: +10",
          "Marital Status: +20",
          "Dependents: 0 (no data or poor indicator)",
          "Home Ownership: 0 (no data or poor indicator)",
          "Age in Employment: 0 (no data or poor indicator)",
          "Business Location: 0 (no data or poor indicator)",
          "Net Income: +32",
          "DSCR / IIR: +11",
          "Banking Turnover: 0 (no data or poor indicator)",
          "Overdue Days: 0 (no data or poor indicator)",
          "Active Loans: +2",
          "Repayment Performance: +15"
        ]
      }
    },
    "willingness_to_pay": {
      "score": 10,
      "classification": "High Risk",
      "positive_signals": [],
      "risk_signals": [
        "Overdue days > 180",
        "Poor credit history"
      ],
      "behavioural_observations": [
        "Significant history of non-repayment"
      ],
      "summary": "The borrower shows a clear pattern of non-compliance with credit obligations, evidenced by the 180+ days past due status.",
      "verdict": "Unwilling to pay",
      "recommended_lending_confidence": "None"
    },
    "capacity_to_pay": {
      "score": 15,
      "classification": "Insufficient",
      "recommended_monthly_repayment": 0,
      "recommended_loan_amount": 0,
      "positive_signals": [
        "High reported monthly inflows"
      ],
      "collateral_valuation": {
        "collateral_type": "Unsecured",
        "receivables_backed": false,
        "total_invoice_value": null,
        "advance_rate_percentage": null,
        "discount_fee_percentage": null,
        "eligible_invoices_count": null,
        "unsecured_portion": null,
        "summary": "No collateral provided or verified.",
        "verdict": "Insufficient"
      },
      "cash_flow_metrics": {
        "monthly_average_inflow": 86905899,
        "income_stability": "STABLE",
        "inflow_outflow_ratio": null
      },
      "risk_signals": [
        "Lack of employment verification",
        "Unknown sector",
        "No salary payments observed"
      ],
      "cashflow_observations": [
        "High inflows are present but lack context or verification of source."
      ],
      "summary": "While inflows are high, the lack of employment data and the inability to verify the source of funds makes the capacity assessment unreliable.",
      "verdict": "Insufficient",
      "lending_recommendation": "Decline"
    },
    "risk_factors": [
      {
        "factor": "Credit History",
        "detail": "Overdue days exceed 180 days, triggering automatic decline.",
        "severity": "high"
      },
      {
        "factor": "TrustScore",
        "detail": "Score of 395 indicates high risk profile.",
        "severity": "high"
      },
      {
        "factor": "Graph Risk",
        "detail": "Graph risk check unavailable; applying conservative risk assessment.",
        "severity": "medium"
      }
    ],
    "macro_context_summary": "Nigeria's economic environment is characterized by high inflation (23.0%) and a tightening monetary policy (CBN MPR 27.5%), creating a challenging landscape for borrowers.",
    "explanation": "The borrower is automatically declined due to severe delinquency (overdue days > 180) reflected in the TrustScore. Despite high reported monthly inflows, the credit history is fundamentally broken, and the lack of employment/sector data prevents a reliable capacity assessment.",
    "override": {
      "agent_overrode_trustscore": false,
      "override_reason": null
    }
  }
}
Sample data

The values in these payloads are illustrative. Use the field names and nesting as the integration contract, and treat values as assessment-specific.

Last updated on