Oracle Cloud Webhooks & Events Skill

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:

| Category | Event Type | Fires When | |----------|-----------|------------| | Compute | com.oraclecloud.computeapi.launchinstance.end | Instance launch completes | | Compute | com.oraclecloud.computeapi.terminateinstance.end | Instance terminated | | Compute | com.oraclecloud.computeapi.instanceaction.end | Stop/start/reboot finishes | | Storage | com.oraclecloud.objectstorage.createbucket | New bucket created | | Storage | com.oraclecloud.objectstorage.deleteobject | Object deleted | | Identity | com.oraclecloud.identitycontrolplane.createuser | New user created | | Identity | com.oraclecloud.identitycontrolplane.updatepolicy | IAM policy modified | | Audit | com.oraclecloud.audit.event | Any auditable action |

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

| Error | Code | Cause | Solution | |-------|------|-------|----------| | NotAuthenticated | 401 | Bad config or API key | Verify ~/.oci/config credentials and key_file path | | NotAuthorizedOrNotFound | 404 | Missing IAM policy or wrong OCID | Add manage cloudevents-rules / manage ons-topics policies | | TooManyRequests | 429 | Rate limited (no Retry-After header) | Back off exponentially; see oraclecloud-rate-limits | | InvalidParameter | 400 | Malformed condition JSON in rule | Validate JSON syntax — condition must be valid JSON, not HCL | | TopicLimitReached | 400 | ONS topic limit (max 100 per compartment) | Delete unused topics or request a limit increase | | InternalError | 500 | OCI service error | Retry after 30 seconds; check https://ocistatus.oraclecloud.com | | SubscriptionPending | — | HTTPS endpoint did not confirm | Check endpoint logs — OCI sends a confirmation POST that must return 200 |

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.

Agent Skills: Oracle Cloud Webhooks & Events

Install this agent skill to your local

Skill Files