Islamic Open Finance™

Appearance

Event Catalog ​

Complete reference for all webhook events in Islamic Open Finance™.

Overview ​

Events are emitted when significant actions occur in the system. Subscribe to events via Webhooks to receive real-time notifications.

Event Structure ​

All events follow this structure:

json
{
  "id": "evt_abc123",
  "type": "contract.created",
  "version": "1.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific payload
  },
  "metadata": {
    "tenantId": "tenant_123",
    "workspaceId": "ws_456"
  }
}

Contract Events ​

Events for Islamic finance contract lifecycle management.

EventDescription
contract.createdNew contract created
contract.updatedContract details modified
contract.executedContract executed and active
contract.approvedContract approved by authority
contract.rejectedContract rejected
contract.maturedContract reached maturity
contract.terminatedContract terminated before maturity
contract.renewedContract renewed for another period
contract.defaultedContract entered default status

Example: contract.created ​

json
{
  "type": "contract.created",
  "data": {
    "contractId": "con_xyz789",
    "contractType": "MURABAHA",
    "status": "DRAFT",
    "tenantId": "tenant_123",
    "customerId": "cust_456",
    "principalAmount": "100000.00",
    "currency": "SAR",
    "startDate": "2024-01-15T00:00:00Z",
    "shariahCompliant": true,
    "createdBy": "user_123",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

KYC Events ​

Events for Know Your Customer verification workflows.

Verification Events ​

EventDescription
kyc.verification.startedKYC verification initiated
kyc.verification.completedVerification completed
kyc.verification.failedVerification failed
kyc.verification.expiredVerification expired

Document Events ​

EventDescription
kyc.document.uploadedDocument uploaded
kyc.document.verifiedDocument verified
kyc.document.rejectedDocument rejected
kyc.document.expiredDocument expired

Screening Events ​

EventDescription
kyc.screening.startedScreening initiated
kyc.screening.completedScreening completed
kyc.screening.match_foundMatch found in screening
kyc.screening.clearedScreening cleared

Risk Events ​

EventDescription
kyc.risk.score_updatedRisk score updated
kyc.risk.level_changedRisk level changed

Example: kyc.verification.completed ​

json
{
  "type": "kyc.verification.completed",
  "data": {
    "subjectId": "cust_123",
    "subjectType": "individual",
    "verificationId": "kyc_abc",
    "result": "approved",
    "riskScore": 25,
    "riskLevel": "low",
    "completedAt": "2024-01-15T12:00:00Z",
    "expiresAt": "2025-01-15T12:00:00Z"
  }
}

Compliance Events ​

Events for regulatory and Shariah compliance workflows.

Alert Events ​

EventDescription
compliance.alert.createdCompliance alert created
compliance.alert.updatedAlert updated
compliance.alert.resolvedAlert resolved
compliance.alert.escalatedAlert escalated

Violation Events ​

EventDescription
compliance.violation.detectedViolation detected
compliance.violation.confirmedViolation confirmed
compliance.violation.remediatedViolation remediated
compliance.violation.waivedViolation waived

Shariah Events ​

EventDescription
compliance.shariah.review_requestedShariah review requested
compliance.shariah.review_completedReview completed
compliance.shariah.approval_grantedApproval granted
compliance.shariah.approval_revokedApproval revoked
compliance.shariah.fatwa_issuedFatwa issued

Audit Events ​

EventDescription
compliance.audit.startedAudit started
compliance.audit.completedAudit completed
compliance.audit.finding_reportedFinding reported

Regulatory Events ​

EventDescription
compliance.regulatory.report_dueReport due
compliance.regulatory.report_submittedReport submitted
compliance.regulatory.deadline_approachingDeadline approaching

AML Events ​

Events for Anti-Money Laundering workflows.

Screening Events ​

EventDescription
aml.screening.startedAML screening started
aml.screening.completedScreening completed
aml.screening.match_foundMatch found
aml.screening.false_positiveFalse positive confirmed

Alert Events ​

EventDescription
aml.alert.createdAML alert created
aml.alert.assignedAlert assigned
aml.alert.updatedAlert updated
aml.alert.closedAlert closed
aml.alert.escalatedAlert escalated

Case Events ​

EventDescription
aml.case.openedInvestigation case opened
aml.case.updatedCase updated
aml.case.closedCase closed
aml.case.referredCase referred

Transaction Events ​

EventDescription
aml.transaction.flaggedTransaction flagged
aml.transaction.clearedTransaction cleared
aml.transaction.blockedTransaction blocked

SAR/STR Events ​

EventDescription
aml.sar.filedSAR filed
aml.sar.submittedSAR submitted to authority
aml.sar.acknowledgedSAR acknowledged

Treasury Events ​

Events for treasury management workflows.

Position Events ​

EventDescription
treasury.position.createdPosition created
treasury.position.updatedPosition updated
treasury.position.closedPosition closed
treasury.position.revaluedPosition revalued

Trade Events ​

EventDescription
treasury.trade.initiatedTrade initiated
treasury.trade.executedTrade executed
treasury.trade.settledTrade settled
treasury.trade.cancelledTrade cancelled
treasury.trade.failedTrade failed

Liquidity Events ​

EventDescription
treasury.liquidity.lowLow liquidity warning
treasury.liquidity.criticalCritical liquidity alert
treasury.liquidity.restoredLiquidity restored

FX Events ​

EventDescription
treasury.fx.rate_updatedFX rate updated
treasury.fx.exposure_thresholdExposure threshold breach
treasury.fx.hedge_executedHedge executed

Cash Flow Events ​

EventDescription
treasury.cashflow.projectedCash flow projected
treasury.cashflow.varianceCash flow variance detected
treasury.cashflow.shortfallCash flow shortfall

Investment Events ​

EventDescription
treasury.investment.maturedInvestment matured
treasury.investment.profit_distributedProfit distributed
treasury.investment.redemptionRedemption processed

Limit Events ​

EventDescription
treasury.limit.breachLimit breached
treasury.limit.warningLimit warning
treasury.limit.updatedLimit updated

Billing Events ​

Events for billing and invoicing.

EventDescription
billing.invoice.createdInvoice created
billing.invoice.paidInvoice paid
billing.invoice.overdueInvoice overdue
billing.subscription.createdSubscription created
billing.subscription.updatedSubscription updated
billing.subscription.cancelledSubscription cancelled

Clearing Events ​

Events for clearing and settlement.

EventDescription
clearing.instruction.receivedInstruction received
clearing.instruction.validatedInstruction validated
clearing.instruction.matchedInstruction matched
clearing.instruction.settledSettlement completed
clearing.instruction.failedSettlement failed

Event Filtering ​

Subscribe to specific events using patterns:

typescript
// All contract events
await iof.webhooks.createEndpoint({
  url: "https://yourapp.com/webhooks",
  events: ["contract.*"],
});

// Specific events only
await iof.webhooks.createEndpoint({
  url: "https://yourapp.com/webhooks",
  events: [
    "contract.created",
    "contract.executed",
    "kyc.verification.completed",
  ],
});

// All events from multiple categories
await iof.webhooks.createEndpoint({
  url: "https://yourapp.com/webhooks",
  events: ["contract.*", "kyc.*", "compliance.*"],
});

Best Practices ​

  1. Subscribe selectively - Only subscribe to events you need
  2. Handle duplicates - Events may be delivered more than once
  3. Process asynchronously - Queue events for background processing
  4. Log event IDs - Track events for debugging
  5. Monitor delivery - Set up alerts for failed deliveries

Next Steps ​

Licensed under the Apache License 2.0

Copyright 2025 Islamic Open Finance™. All rights reserved.