send_slack_notification

send_slack_notification(webhook_url: str, text: str) -> dict

Sends a message to a Slack channel using an Incoming Webhook URL. Useful for notifying your team about events during a conversation — refund requests, escalations, high-value orders, etc.

Parameters

Returns

dict — {"success": bool, "message": str}

Examples

Notify your team about a refund request

def execute_action(context):
    order_id = context["args"]["orderId"]
    reason = context["args"]["reason"]
    conv_id = context["conversation"]["publicId"]

    send_slack_notification(
        "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
        f"*Refund requested*\nOrder: {order_id}\nReason: {reason}\nConversation: {conv_id}",
    )

    return {"success": True, "message": "Your refund request has been submitted."}

Alert on high-value orders

def execute_action(context):
    order = fetch_order(context["args"]["orderId"])

    if order["total"] > 500:
        send_slack_notification(
            "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
            f"*High-value order placed*\nOrder: {order['id']}\nTotal: ${order['total']}\nCustomer: {order['email']}",
        )

    return {"orderId": order["id"], "status": order["status"]}

Setting up an Incoming Webhook

Before you can call send_slack_notification, you need a Slack Incoming Webhook URL. This is a one-time setup per channel.

Step 1 — Create a Slack app

1. Go to api.slack.com/apps and click Create New App
2. Choose From scratch
3. Give it a name (e.g., "Octocom Notifications") and select the workspace you want to post to
4. Click Create App

Step 2 — Enable Incoming Webhooks

1. In the app settings sidebar, click Incoming Webhooks
2. Toggle Activate Incoming Webhooks to On

Step 3 — Create a webhook for a channel

1. Click Add New Webhook to Workspace
2. Select the channel where you want notifications to appear (e.g., #customer-support)
3. Click Allow
4. Slack generates a webhook URL that looks like:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

5. Copy this URL — you'll pass it to send_slack_notification as webhook_url

Adding more channels

Repeat Step 3 for each channel you want to post to. Each channel gets its own webhook URL. You can use different URLs in different actions to route notifications to the right team.

Security

• Treat the webhook URL as a secret. Anyone with the URL can post to your channel.
• Do not share webhook URLs in public repositories or client-facing code.
• If a webhook URL is compromised, revoke it in the Slack app settings and create a new one.