Recipe 01 — Pipe KYC + cluster events into a Slack war room

15 minutes. Result: every kyc.match_detected, cluster.entity_severity_changed, and watchlist.match_detected event renders as a native Slack Block Kit card in your compliance channel.

What this recipe does

1. Creates a Slack incoming webhook.
2. Subscribes that URL to OilFlow webhook events with delivery_format: "slack".
3. OilFlow's webhook dispatcher renders each event as a Slack Block Kit card with severity color coding before POSTing.
4. No HMAC secret needed — the Slack URL is the auth.

Step 1 — Create a Slack incoming webhook

In Slack:

• App directory → Add an app → "Incoming Webhooks"
• Pick the channel (e.g. #oilflow-alerts)
• Copy the URL — it looks like https://hooks.slack.com/services/T.../B.../...

Step 2 — Subscribe via SDK

Node

import OilFlow from "@oilflow/sdk";

const client = new OilFlow();

const { id } = await client.webhooks.create({
  url: "https://hooks.slack.com/services/T.../B.../...",
  delivery_format: "slack",
  events: [
    "kyc.match_detected",
    "cluster.entity_severity_changed",
    "watchlist.match_detected",
    "adverse_media.match_detected",
  ],
  description: "#oilflow-alerts",
});
console.log("subscription:", id);

Python

from oilflow import Client

client = Client()

sub = client.webhooks.create(
    url="https://hooks.slack.com/services/T.../B.../...",
    delivery_format="slack",
    events=[
        "kyc.match_detected",
        "cluster.entity_severity_changed",
        "watchlist.match_detected",
        "adverse_media.match_detected",
    ],
    description="#oilflow-alerts",
)
print("subscription:", sub["id"])

curl

curl -X POST -H "Authorization: Bearer $OILFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/T.../B.../...",
    "delivery_format": "slack",
    "events": ["kyc.match_detected","cluster.entity_severity_changed","watchlist.match_detected","adverse_media.match_detected"],
    "description": "#oilflow-alerts"
  }' \
  https://oilflow.us/api/v1/webhooks

Step 3 — Verify

Trigger a sample event from /dashboard → Webhooks → Test send, or fire a real KYC screen that hits the cluster blocklist:

curl -X POST -H "Authorization: Bearer $OILFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name":"SSW Kafcima","directors":["Simar Chahal"]}' \
  https://oilflow.us/api/v1/kyc/screen

The Slack channel receives a card with the entity name, severity, verdict, and a deep link back to the OilFlow dashboard.

Field-mapping notes

Full block-rendering source: `shared/webhook_formatters/slack.py`.

Common gotchas

• URL doesn't start with `https://hooks.slack.com/` — the create call returns 400 with error_code: "url_must_be_slack_incoming_webhook".
• Channel was archived — Slack returns 404. OilFlow logs the failure to your /api/v1/webhooks/events audit and marks the subscription consecutive_failures+1. After 5, the dispatcher pauses delivery.
• Want both Slack AND a raw HMAC delivery to your SIEM? Create two subscriptions — one with delivery_format: "slack", one with delivery_format: "raw". Each delivery is independent.

Next steps

• Recipe 02: React intake-form integration
• Recipe 03: Watchlist polling from your CRM