supabase_webhook_guide.md

🔌 Supabase Audit Webhook Integration Guide

This guide explains how to configure Supabase Database Webhooks to send real-time alerts (e.g., to Slack, MS Teams, or Discord) whenever a user performs a financial statement analysis and a new entry is added to the financial_analysis_audit table.

---

1. Supabase Dashboard Configuration

Follow these steps to enable the database webhook directly in the Supabase Dashboard:

1. Navigate to Database Webhooks:

   • Go to your Supabase Project Dashboard.
   • Select your project, click on Database in the left sidebar, and click on Webhooks (or go to Integrations -> Webhooks).
   • Click the Enable Webhooks button if webhooks are not already enabled.

2. Create Webhook:

   • Click Create Webhook.
   • Name: send_audit_notification
   • Schema: public
   • Table: financial_analysis_audit
   • Events: Toggle on INSERT only (so it fires only when a new log is created).
   • Webhook Type: Select HTTP POST.
   • HTTP URL:
     • If routing via Zapier/Make, enter your webhook trigger URL.
     • If routing directly to Slack, enter your Supabase Edge Function URL (see Section 3 for direct Slack formatting).
   • Timeout: 10 seconds (default).
   • Click Create Webhook.

---

2. Event Payload Schema

When a new row is inserted, Supabase POSTs a JSON payload with the following schema:

{
  "type": "INSERT",
  "table": "financial_analysis_audit",
  "schema": "public",
  "record": {
    "id": 42,
    "timestamp": "2026-05-22T10:09:00Z",
    "user_email": "analyst@company.com",
    "company_ticker": "TCS.NS",
    "company_name": "Tata Consultancy Services Limited",
    "selected_formats": "xlsx, docx, pptx",
    "ai_model_used": "groq, gemini",
    "status": "completed"
  },
  "old_record": null
}

---

3. Formatting for Slack / Teams (Supabase Edge Function)

Since Slack and Teams require specific JSON formats (e.g., {"text": "..."}), you cannot point the Supabase Database Webhook directly to Slack's webhook URL without a translator.

Below is the code for a lightweight Supabase Edge Function in TypeScript that acts as a translator.

Edge Function Code (index.ts)

import { serve } from "https://deno.land/std@0.168.0/http/server.ts"

const SLACK_WEBHOOK_URL = Deno.env.get("SLACK_WEBHOOK_URL") || "";

serve(async (req) => {
  try {
    const payload = await req.json();
    const record = payload.record;

    if (!record) {
      return new Response(JSON.stringify({ error: "No record found" }), { status: 400 });
    }

    // Build a rich Slack block layout
    const slackMessage = {
      text: `📈 New Financial Analysis Run: ${record.company_name} (${record.company_ticker})`,
      blocks: [
        {
          type: "header",
          text: {
            type: "plain_text",
            text: "📈 Financial Statement Analysis Logged",
            emoji: true
          }
        },
        {
          type: "section",
          fields: [
            {
              type: "mrkdwn",
              text: `*User:* \`${record.user_email}\``
            },
            {
              type: "mrkdwn",
              text: `*Company:* *${record.company_name}* (\`${record.company_ticker}\`)`
            },
            {
              type: "mrkdwn",
              text: `*Formats Generated:* \`${record.selected_formats}\``
            },
            {
              type: "mrkdwn",
              text: `*AI Engines Used:* \`${record.ai_model_used}\``
            }
          ]
        },
        {
          type: "context",
          elements: [
            {
              type: "mrkdwn",
              text: `*Status:* ${record.status === "completed" ? "✅ Completed Successfully" : "❌ Failed"}  |  *Time:* \`${record.timestamp}\``
            }
          ]
        }
      ]
    };

    // Forward formatted payload to Slack
    const response = await fetch(SLACK_WEBHOOK_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(slackMessage),
    });

    return new Response(JSON.stringify({ success: true }), { status: 200 });

  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), { status: 500 });
  }
})

Steps to Deploy the Edge Function:

1. Install Supabase CLI: npm install -g supabase
2. Login: supabase login
3. Initialize in your folder: supabase init
4. Create Edge Function: supabase functions new slack-notifier
5. Replace the generated code in supabase/functions/slack-notifier/index.ts with the TypeScript code above.
6. Set the Slack Webhook secret:

   supabase secrets set SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
   

7. Deploy the function:

   supabase functions deploy slack-notifier --project-ref your-project-ref-id
   

8. Set the Webhook URL in Supabase Dashboard to point to your new deployed function: https://your-project-ref-id.supabase.co/functions/v1/slack-notifier