Oracle Cloud Webhooks & Events

Overview

Build event-driven workflows using the OCI Events service, Oracle Notification Service (ONS), and OCI Functions. OCI Events monitors resource state changes across your tenancy and fires rules that route events to ONS topics, streaming, or Functions. This skill covers event rule creation, ONS topic/subscription setup, event pattern matching syntax, and Functions integration.

Purpose: Create reliable event-driven pipelines that react to OCI resource changes in real time.

Prerequisites

• OCI Python SDK — pip install oci
• OCI config file at ~/.oci/config with valid credentials (user, fingerprint, tenancy, region, key_file)
• IAM policies granting access to Events, ONS, and Functions:
  • Allow group EventAdmins to manage cloudevents-rules in compartment <name>
  • Allow group EventAdmins to manage ons-topics in compartment <name>
  • Allow group EventAdmins to use fn-function in compartment <name>
• Compartment OCID for the target compartment
• Python 3.8+

Instructions

Step 1: Create an ONS Topic and Subscription

Create a notification topic that will receive events, then subscribe an endpoint (email, HTTPS, PagerDuty, or Slack via HTTPS):

import oci

config = oci.config.from_file("~/.oci/config")
ons_control = oci.ons.NotificationControlPlaneClient(config)
ons_data = oci.ons.NotificationDataPlaneClient(config)

# Create a topic
topic_response = ons_control.create_topic(
    oci.ons.models.CreateTopicDetails(
        name="infra-alerts",
        compartment_id="ocid1.compartment.oc1..example",
        description="Infrastructure lifecycle alerts"
    )
)
topic_id = topic_response.data.topic_id
print(f"Topic created: {topic_id}")

# Subscribe an HTTPS endpoint (e.g., Slack incoming webhook)
subscription = ons_data.create_subscription(
    oci.ons.models.CreateSubscriptionDetails(
        topic_id=topic_id,
        compartment_id="ocid1.compartment.oc1..example",
        protocol="HTTPS",
        endpoint="https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK"
    )
)
print(f"Subscription: {subscription.data.id} ({subscription.data.lifecycle_state})")

Step 2: Create an Events Rule

Events rules use a condition block that matches on eventType, compartmentId, and optional attribute filters. The condition syntax is JSON, not HCL:

events_client = oci.events.EventsClient(config)

rule = events_client.create_rule(
    oci.events.models.CreateRuleDetails(
        display_name="instance-state-changes",
        compartment_id="ocid1.compartment.oc1..example",
        description="Fire on compute instance lifecycle changes",
        is_enabled=True,
        condition='{"eventType":["com.oraclecloud.computeapi.launchinstance.end","com.oraclecloud.computeapi.terminateinstance.end","com.oraclecloud.computeapi.instanceaction.end"]}',
        actions=oci.events.models.ActionDetailsList(
            actions=[
                oci.events.models.ActionDetails(
                    action_type="ONS",
                    topic_id=topic_id,
                    is_enabled=True,
                    description="Notify infra-alerts topic"
                )
            ]
        )
    )
)
print(f"Rule created: {rule.data.id}")

Step 3: Common Event Types Reference

Use these exact eventType strings in your rule conditions:

Step 4: Route Events to a Function

For complex processing, route events to an OCI Function instead of (or in addition to) ONS:

# Create a rule that invokes a Function
fn_rule = events_client.create_rule(
    oci.events.models.CreateRuleDetails(
        display_name="bucket-change-processor",
        compartment_id="ocid1.compartment.oc1..example",
        is_enabled=True,
        condition='{"eventType":["com.oraclecloud.objectstorage.createobject","com.oraclecloud.objectstorage.deleteobject"]}',
        actions=oci.events.models.ActionDetailsList(
            actions=[
                oci.events.models.ActionDetails(
                    action_type="FAAS",
                    function_id="ocid1.fnfunc.oc1.iad.example",
                    is_enabled=True,
                    description="Process bucket changes"
                )
            ]
        )
    )
)

Step 5: Verify the Pipeline

List active rules and test by triggering an event:

# List event rules via CLI
oci events rule list --compartment-id ocid1.compartment.oc1..example --all

# Check ONS subscription confirmation status
oci ons subscription list --compartment-id ocid1.compartment.oc1..example --topic-id <topic-ocid>

Output

Successful completion produces:

• An ONS topic with at least one confirmed subscription (email, HTTPS, or PagerDuty)
• One or more Events rules with condition filters matching target event types
• Verified event delivery — triggering a matched action (e.g., stopping an instance) delivers a notification to the subscribed endpoint

Error Handling

Examples

Quick event rule via CLI:

# Create a rule that fires on all audit events in a compartment
oci events rule create \
  --compartment-id ocid1.compartment.oc1..example \
  --display-name "audit-all" \
  --is-enabled true \
  --condition '{"eventType":["com.oraclecloud.audit.event"]}' \
  --actions '{"actions":[{"actionType":"ONS","topicId":"ocid1.onstopic.oc1.iad.example","isEnabled":true}]}'

List all event types available:

import oci

config = oci.config.from_file("~/.oci/config")
events_client = oci.events.EventsClient(config)

# Event types are documented — no list API exists.
# Reference: https://docs.oracle.com/en-us/iaas/Content/Events/Reference/eventsproducers.htm

Resources

• OCI Events Service — event rules and conditions
• OCI Notification Service (ONS) — topics and subscriptions
• Event Types Reference — all available event types
• Python SDK Reference — EventsClient, NotificationDataPlaneClient
• OCI Status — service health dashboard

Next Steps

After event pipelines are running, see oraclecloud-observability for monitoring event delivery metrics, or oraclecloud-rate-limits for handling 429 errors in high-volume event processing.