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:

{
  "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.

Event	Description
`contract.created`	New contract created
`contract.updated`	Contract details modified
`contract.executed`	Contract executed and active
`contract.approved`	Contract approved by authority
`contract.rejected`	Contract rejected
`contract.matured`	Contract reached maturity
`contract.terminated`	Contract terminated before maturity
`contract.renewed`	Contract renewed for another period
`contract.defaulted`	Contract entered default status

Example: contract.created

{
  "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

Event	Description
`kyc.verification.started`	KYC verification initiated
`kyc.verification.completed`	Verification completed
`kyc.verification.failed`	Verification failed
`kyc.verification.expired`	Verification expired

Document Events

Event	Description
`kyc.document.uploaded`	Document uploaded
`kyc.document.verified`	Document verified
`kyc.document.rejected`	Document rejected
`kyc.document.expired`	Document expired

Screening Events

Event	Description
`kyc.screening.started`	Screening initiated
`kyc.screening.completed`	Screening completed
`kyc.screening.match_found`	Match found in screening
`kyc.screening.cleared`	Screening cleared

Risk Events

Event	Description
`kyc.risk.score_updated`	Risk score updated
`kyc.risk.level_changed`	Risk level changed

Example: kyc.verification.completed

{
  "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

Event	Description
`compliance.alert.created`	Compliance alert created
`compliance.alert.updated`	Alert updated
`compliance.alert.resolved`	Alert resolved
`compliance.alert.escalated`	Alert escalated

Violation Events

Event	Description
`compliance.violation.detected`	Violation detected
`compliance.violation.confirmed`	Violation confirmed
`compliance.violation.remediated`	Violation remediated
`compliance.violation.waived`	Violation waived

Shariah Events

Event	Description
`compliance.shariah.review_requested`	Shariah review requested
`compliance.shariah.review_completed`	Review completed
`compliance.shariah.approval_granted`	Approval granted
`compliance.shariah.approval_revoked`	Approval revoked
`compliance.shariah.fatwa_issued`	Fatwa issued

Audit Events

Event	Description
`compliance.audit.started`	Audit started
`compliance.audit.completed`	Audit completed
`compliance.audit.finding_reported`	Finding reported

Regulatory Events

Event	Description
`compliance.regulatory.report_due`	Report due
`compliance.regulatory.report_submitted`	Report submitted
`compliance.regulatory.deadline_approaching`	Deadline approaching

AML Events

Events for Anti-Money Laundering workflows.

Screening Events

Event	Description
`aml.screening.started`	AML screening started
`aml.screening.completed`	Screening completed
`aml.screening.match_found`	Match found
`aml.screening.false_positive`	False positive confirmed

Alert Events

Event	Description
`aml.alert.created`	AML alert created
`aml.alert.assigned`	Alert assigned
`aml.alert.updated`	Alert updated
`aml.alert.closed`	Alert closed
`aml.alert.escalated`	Alert escalated

Case Events

Event	Description
`aml.case.opened`	Investigation case opened
`aml.case.updated`	Case updated
`aml.case.closed`	Case closed
`aml.case.referred`	Case referred

Transaction Events

Event	Description
`aml.transaction.flagged`	Transaction flagged
`aml.transaction.cleared`	Transaction cleared
`aml.transaction.blocked`	Transaction blocked

SAR/STR Events

Event	Description
`aml.sar.filed`	SAR filed
`aml.sar.submitted`	SAR submitted to authority
`aml.sar.acknowledged`	SAR acknowledged

Treasury Events

Events for treasury management workflows.

Position Events

Event	Description
`treasury.position.created`	Position created
`treasury.position.updated`	Position updated
`treasury.position.closed`	Position closed
`treasury.position.revalued`	Position revalued

Trade Events

Event	Description
`treasury.trade.initiated`	Trade initiated
`treasury.trade.executed`	Trade executed
`treasury.trade.settled`	Trade settled
`treasury.trade.cancelled`	Trade cancelled
`treasury.trade.failed`	Trade failed

Liquidity Events

Event	Description
`treasury.liquidity.low`	Low liquidity warning
`treasury.liquidity.critical`	Critical liquidity alert
`treasury.liquidity.restored`	Liquidity restored

FX Events

Event	Description
`treasury.fx.rate_updated`	FX rate updated
`treasury.fx.exposure_threshold`	Exposure threshold breach
`treasury.fx.hedge_executed`	Hedge executed

Cash Flow Events

Event	Description
`treasury.cashflow.projected`	Cash flow projected
`treasury.cashflow.variance`	Cash flow variance detected
`treasury.cashflow.shortfall`	Cash flow shortfall

Investment Events

Event	Description
`treasury.investment.matured`	Investment matured
`treasury.investment.profit_distributed`	Profit distributed
`treasury.investment.redemption`	Redemption processed

Limit Events

Event	Description
`treasury.limit.breach`	Limit breached
`treasury.limit.warning`	Limit warning
`treasury.limit.updated`	Limit updated

Billing Events

Events for billing and invoicing.

Event	Description
`billing.invoice.created`	Invoice created
`billing.invoice.paid`	Invoice paid
`billing.invoice.overdue`	Invoice overdue
`billing.subscription.created`	Subscription created
`billing.subscription.updated`	Subscription updated
`billing.subscription.cancelled`	Subscription cancelled

Clearing Events

Events for clearing and settlement.

Event	Description
`clearing.instruction.received`	Instruction received
`clearing.instruction.validated`	Instruction validated
`clearing.instruction.matched`	Instruction matched
`clearing.instruction.settled`	Settlement completed
`clearing.instruction.failed`	Settlement failed

Event Filtering

Subscribe to specific events using patterns:

// 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

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

Next Steps

Webhooks Guide - Webhook setup and handling
Webhooks API - Endpoint management
SDK Webhooks - SDK integration