Oracle ERP Cloud Business Events — Subscription Model, Event Catalog, and Webhook Delivery

TL;DR

• Bottom line: Oracle ERP Cloud publishes business events through the Event Handling Framework (EHF) to Oracle Integration Cloud (OIC) — you subscribe via the ERP Cloud Adapter, not via raw webhooks. Events cover Financials, Procurement, SCM, Manufacturing, and PPM with 100+ predefined events.
• Key limit: No direct webhook endpoint — all event subscriptions route through OIC or compatible iPaaS. Maximum 10 automatic retries per failed delivery, 6-hour backlog window on reactivation.
• Watch out for: Many events are disabled by default (especially Payables). You must enable them via REST API or profile option (e.g., ORA_AP_ENABLE_BUSINESS_EVENTS = Y) before they fire.
• Best for: Event-driven outbound integration patterns — real-time notifications when POs are approved, invoices created, receipts posted, or GL periods opened.
• Authentication: Username-Password Token (recommended for event triggers) or OAuth JWT User Assertion. Token-based session auth is auto-managed for event delivery.

System Profile

Oracle Fusion Cloud ERP provides a native event-driven integration capability through its Event Handling Framework (EHF). This framework propagates business events beyond the application boundary to external subscribers, primarily through Oracle Integration Cloud (OIC) using the Oracle ERP Cloud Adapter. The events system covers ERP, SCM, Manufacturing, and Project Portfolio Management modules. On-premise Oracle E-Business Suite does NOT use this event framework.

API Surfaces & Capabilities

Oracle ERP Cloud does not expose business events as raw HTTP webhooks. The Event Handling Framework (EHF) manages event propagation through a pub/sub architecture where OIC or compatible middleware acts as the subscriber.

Rate Limits & Quotas

Per-Event Delivery Limits

Event Processing Limits

Authentication

Authentication Gotchas

• OAuth-configured trigger connections may fail to receive events — use Username-Password Token for trigger (event subscription) connections. [src3]
• Token-based authentication for business events is automatic and self-managed — session tokens are generated, validated, cached, and never persisted on disk. [src1]
• The integration user must have the ServiceAdministrator role in OIC to access event monitoring on the Fusion Applications observability page. [src2]

Constraints

• OIC required: Business events cannot be delivered to arbitrary HTTP endpoints. You need Oracle Integration Cloud (OIC) with the ERP Cloud Adapter, or a compatible iPaaS.
• No private endpoint support: VCN private subnet connections do NOT support business event subscriptions.
• Events disabled by default: Many events (especially Payables, some Receivables) are shipped disabled. Enable via REST API or profile options.
• 6-hour redelivery window: If integration is deactivated without deleting subscription, queued events redelivered only within 6 hours.
• 10 retry maximum: After 10 failed delivery attempts, events require manual intervention via OIC monitoring console.
• Summary payloads only: Event payloads contain key identifiers, not full record details. Follow-up REST API call required for complete data.
• Cross-environment risk: Test environment subscriptions can accidentally target production OIC endpoints after environment refresh.

Integration Pattern Decision Tree

START — Need to receive Oracle ERP Cloud events in external system
|
+-- Do you have Oracle Integration Cloud (OIC)?
|   +-- YES -> Configure ERP Cloud Adapter trigger connection
|   |          Select business events from Event Catalog
|   |          Apply XPath filter expressions (optional)
|   |          Activate integration -> subscription auto-created
|   +-- NO -> Compatible iPaaS (Workato, MuleSoft, Celigo)?
|       +-- YES -> Use vendor's Oracle Fusion adapter
|       +-- NO -> Custom: query Event Catalog REST, manage subscriptions via REST API
|                 (NOT recommended - significant maintenance burden)
|
+-- Which events do you need?
|   +-- Financial (AP, AR, GL, Payments) -> Check if enabled (many disabled by default)
|   +-- Procurement (PO, Supplier) -> PO Event enabled by default
|   +-- SCM/Manufacturing (Inventory, WO, OM) -> Most enabled by default
|   +-- Bulk import completion (FBDI callback) -> Use ErpImportBulkDataEvent
|
+-- Need event filtering?
|   +-- YES -> Apply XPath filter on event payload
|   +-- NO -> Subscribe to all instances of the event
|
+-- Error tolerance?
    +-- Zero-loss -> Monitor via OIC observability, alert on maxed retries
    +-- Best-effort -> Standard 10-retry mechanism usually sufficient

Quick Reference — Available Business Events by Module

Step-by-Step Integration Guide

1. Discover Available Events via the Event Catalog

Query the public event catalog REST endpoint to see all available business events for your Fusion instance. [src3]

# Query event catalog
curl -u "integration_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/catalog"

# Query custom events only
curl -u "integration_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/customCatalog"

Verify: Response returns JSON array with event names and namespace URIs.

2. Enable Disabled Events

Many events (especially Payables) are disabled by default. Enable via profile option or REST API. [src6]

# Enable Payables events via profile option:
# Navigate: Setup and Maintenance > Manage Administrator Profile Values
# Search: ORA_AP_ENABLE_BUSINESS_EVENTS > Set to Y

# Or enable via REST API:
curl -X PATCH -u "admin_user:password" \
  -H "Content-Type: application/json" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/fscmRestApi/resources/latest/erpBusinessEvents/{eventName}" \
  -d '{"EnabledFlag": "Y"}'

Verify: Enabled events appear in the OIC adapter's event selection wizard.

3. Configure OIC ERP Cloud Adapter Connection

Create a trigger connection in OIC using the ERP Cloud Adapter with Username-Password Token security. [src1]

OIC Console:
1. Integrations > Connections > Create
2. Select "Oracle ERP Cloud" adapter
3. Configure: ERP Cloud Host URL, Username Password Token security
4. Test Connection -> verify "100% Configured"
5. Save

Verify: Connection shows green "Configured" status.

4. Create Event Subscription Integration

Build an App Driven Orchestration integration that subscribes to the desired business event. [src4]

OIC Console:
1. Create Integration > App Driven Orchestration
2. Add Trigger: drag ERP Cloud Adapter connection
3. Select "Receive Business Events raised within ERP Cloud"
4. Choose event (e.g., "Purchase Order Event")
5. Optionally add XPath Filter Expression
6. Map event payload to target system
7. Activate Integration -> subscription auto-created

Verify: Check OIC Observability > Fusion Applications — subscription should appear as "Active."

5. Apply Event Filter Expressions (Optional)

Filter events using XPath expressions on the event payload. [src4]

<!-- Filter PO events by item description -->
<xpathExpr
  xmlns:ns0="http://xmlns.oracle.com/apps/prc/po/editDocument/purchaseOrderServiceV2/"
  xmlns:ns2="http://xmlns.oracle.com/apps/prc/po/editDocument/purchaseOrderServiceV2/types/">
  $eventPayload/ns2:result/ns0:Value/ns0:PurchaseOrderLine/ns0:ItemDescription="Lan Cable"
</xpathExpr>

Verify: Create test POs matching and not matching the filter — only matching events trigger the integration.

6. Monitor Event Delivery

Use the OIC Fusion Applications observability page to track delivery status. [src2]

OIC Console > Observability > Fusion Applications

Event delivery statuses:
- Queued: waiting to be delivered
- Delivered: successfully sent to OIC
- Retried: delivery reattempted (up to 10 times)
- Maxed out retries: failed after 10 attempts (manual retry required)

Verify: Create a test transaction — event should appear with "Delivered" status within seconds.

Code Examples

Python: Querying the Event Catalog

# Input:  Oracle Fusion Cloud credentials and host URL
# Output: List of available business events

import requests
from requests.auth import HTTPBasicAuth

FUSION_HOST = "https://your-instance.oraclecloud.com"
USERNAME = "integration_user"
PASSWORD = "your_password"

def get_event_catalog():
    url = f"{FUSION_HOST}/soa-infra/PublicEvent/catalog"
    resp = requests.get(url, auth=HTTPBasicAuth(USERNAME, PASSWORD), timeout=30)
    resp.raise_for_status()
    events = resp.json()
    for event in events:
        print(f"Event: {event.get('name', 'N/A')}")
    return events

catalog = get_event_catalog()
print(f"Total events available: {len(catalog)}")

Python: Managing Event Subscriptions

# Input:  Oracle Fusion Cloud credentials
# Output: List of active event subscriptions

import requests
from requests.auth import HTTPBasicAuth

FUSION_HOST = "https://your-instance.oraclecloud.com"

def list_subscriptions():
    url = f"{FUSION_HOST}/soa-infra/PublicEvent/subscriptions"
    resp = requests.get(url, auth=HTTPBasicAuth("admin", "pass"), timeout=30)
    resp.raise_for_status()
    return resp.json()

def delete_subscription(subscription_id):
    url = f"{FUSION_HOST}/soa-infra/PublicEvent/subscriptions/{subscription_id}"
    resp = requests.delete(url, auth=HTTPBasicAuth("admin", "pass"), timeout=30)
    resp.raise_for_status()
    print(f"Deleted subscription: {subscription_id}")

cURL: Event Subscription Inspection

# List all subscriptions
curl -u "admin_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/subscriptions"

# Delete a stale subscription
curl -X DELETE -u "admin_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/subscriptions/{id}"

# Check event catalog
curl -u "integration_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/catalog" \
  | python3 -m json.tool

Data Mapping

Event Payload Structure

Data Type Gotchas

• Event payloads use Oracle's internal XML namespaces — you must match the exact namespace URI when building XPath filter expressions. Wrong namespace silently filters out all events. [src4]
• Datetime fields follow Oracle's UTC format (YYYY-MM-DDTHH:MM:SS.sssZ). Convert explicitly for local-time downstream systems. [src1]
• Amount fields may not include currency code — fetch full record via REST API for multi-currency environments.
• The documentName field in FBDI callback events identifies the import job type — use this to route callbacks to different processing logic. [src1]

Error Handling & Failure Points

Common Error Scenarios

Failure Points in Production

• Silent event loss on deactivation: If you deactivate an integration and delete the subscription, all queued events are permanently lost. Fix: Never delete subscription during maintenance. Reactivate within 6 hours. [src3]
• Payables events never fire: Payables events are disabled by default. Most common support ticket for new implementations. Fix: Set ORA_AP_ENABLE_BUSINESS_EVENTS = Y. [src3]
• Test-to-production subscription leak: Event subscriptions survive environment clone/refresh. Fix: After every refresh, list and delete stale subscriptions via /soa-infra/PublicEvent/subscriptions. [src3]
• Filter expression namespace mismatch: XPath filters silently fail on wrong namespace URI. Fix: Copy exact namespace URIs from event catalog. Test with permissive filter first. [src4]

Anti-Patterns

Wrong: Polling REST API for changes instead of using business events

# BAD — polling Fusion REST API every 5 minutes for new POs
# Wastes API quota, adds latency, misses rapid changes
import time
while True:
    response = requests.get(
        f"{FUSION_HOST}/fscmRestApi/resources/latest/purchaseOrders"
        f"?q=CreationDate > '{last_check}'", auth=auth)
    process_new_pos(response.json())
    time.sleep(300)

Correct: Subscribe to Purchase Order Event via OIC

# GOOD — event-driven, near-real-time, no wasted API calls
# 1. ERP Cloud Adapter trigger -> "Purchase Order Event"
# 2. Event fires immediately when PO is approved
# 3. Integration calls REST API for full details
# 4. Forward to downstream system
# Result: <1s latency, zero polling overhead

Wrong: Storing full business object data from event payload

# BAD — assuming event payload contains complete record
def process_po_event(event_payload):
    po_data = extract_from_payload(event_payload)
    insert_to_warehouse(po_data)  # Missing most fields

Correct: Using event as trigger, then fetching full record via REST

# GOOD — event triggers, REST API fetches full data
def process_po_event(event_payload):
    po_header_id = extract_header_id(event_payload)
    full_po = requests.get(
        f"{FUSION_HOST}/fscmRestApi/resources/latest/"
        f"purchaseOrders/{po_header_id}?expand=lines", auth=auth).json()
    insert_to_warehouse(full_po)  # Complete record

Wrong: Deleting event subscription during planned maintenance

# BAD — deleting subscription loses all queued events
def maintenance_mode():
    deactivate_integration(delete_subscription=True)
    # All events during maintenance are PERMANENTLY LOST

Correct: Keeping subscription active during maintenance

# GOOD — keep subscription, events queue for redelivery (up to 6 hours)
def maintenance_mode():
    deactivate_integration(delete_subscription=False)
    # Complete maintenance within 6 hours
    reactivate_integration()
    # Backlogged events are automatically redelivered

Common Pitfalls

• Assuming all events are enabled by default: Many Financials events ship disabled. Fix: Query /soa-infra/PublicEvent/catalog and cross-reference with ERP Business Events REST API. [src3]
• Using OAuth for trigger connections: OAuth-configured triggers may fail to receive events. Fix: Use Username-Password Token for all trigger connections. Reserve OAuth for invoke. [src3]
• Not cleaning up subscriptions after environment refresh: Subscriptions survive environment clones. Fix: After every refresh, GET /soa-infra/PublicEvent/subscriptions and DELETE stale entries. [src3]
• Ignoring the 6-hour backlog window: Events are not redelivered indefinitely. Fix: Design for <6 hour maintenance windows. Implement reconciliation job for longer outages. [src3]
• Not monitoring "maxed out retries": After 10 failed retries, events stop silently. Fix: Set up monitoring alerts. Check for "maxed out retries" status daily. [src2]
• Expecting webhook-style direct delivery: Events route through OIC/iPaaS only. Fix: Budget for OIC or compatible iPaaS as part of the integration architecture. [src1]

Diagnostic Commands

# Check event catalog (all standard events)
curl -u "integration_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/catalog" \
  | python3 -m json.tool | head -50

# Check custom events catalog
curl -u "integration_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/customCatalog"

# List active event subscriptions
curl -u "admin_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/subscriptions"

# Delete a specific stale subscription
curl -X DELETE -u "admin_user:password" \
  "https://YOUR_FUSION_HOST.oraclecloud.com/soa-infra/PublicEvent/subscriptions/{ID}"

# Monitor event delivery in OIC Console:
# Navigate: Observability > Fusion Applications
# Filter by: connection name, time range, status

Version History & Compatibility

Oracle Fusion Cloud follows a quarterly release cadence (A/B/C/D per year). Business event APIs are backward-compatible within major releases. New events are added each quarter. The Event Handling Framework is the strategic direction with no sunset planned.

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• Event availability varies by quarterly release — always check your instance's event catalog at /soa-infra/PublicEvent/catalog for the definitive list.
• The 100+ event count represents commonly used events. The actual catalog may contain more depending on your Fusion instance modules and patches.
• Custom business events created in Application Composer are only visible at /soa-infra/PublicEvent/customCatalog, not the standard catalog endpoint.
• Event payloads are intentionally lightweight (summary/key fields only). This requires a follow-up REST API call for full record details.
• Oracle is developing OCI Events service integration as a more cloud-native alternative. Check Oracle CloudWorld announcements for roadmap updates.
• This card reflects Release 24A-26A capabilities. Oracle adds new events each quarterly release — verify against current release notes.