#Supabase Integration

The Supabase integration allows you to automatically import leads from any table in your Supabase project into your TheVibeCRM pipeline. It supports three modes:

Real-time sync via Supabase Database Webhooks (recommended)
Manual sync triggered from the dashboard
Secure OAuth connection — no API keys to copy or paste

#Prerequisites

→A Supabase project with at least one table containing lead data (e.g. contacts, signups)
→A Supabase account — you will authorize TheVibeCRM via OAuth. No API keys or project URLs needed.

#Step-by-step Setup

#1. Connect Supabase in TheVibeCRM

Go to Project Settings → Integrations → Supabase
Click Connect with Supabase
You are redirected to Supabase to review and authorize the requested permissions
After authorizing, return to TheVibeCRM and select which Supabase project to connect from the list of your projects
Click Confirm Project — the connection is saved automatically

Security

TheVibeCRM uses OAuth 2.0 with PKCE to connect to your Supabase account. Only the minimum required permissions are requested (Projects: read, Secrets: read, Database: write). Your Supabase password is never shared with TheVibeCRM, and you can revoke access at any time from your Supabase organization settings.

#2. Configure a Listener

A listener watches a specific Supabase table and creates leads when new rows are inserted.

After connecting, click Add Listener
Select the Table you want to monitor (tables are auto-discovered from your Supabase schema)
Map columns to lead fields:

Lead Field	Description	Required
`name`	Lead's full name	Yes
`email`	Lead's email address	Yes
`phone`	Phone number	No
`companyName`	Company name	No
`companyUrl`	Company website	No
`source`	Lead source label (defaults to "Supabase")	No
`value`	Monetary value (decimal)	No
`recurrence`	"One-time" or "Recurring" (defaults to "One-time")	No

4. Choose a Target Pipeline Stage — new leads will be placed in this stage.

5. Save the listener — the webhook trigger is registered in your Supabase project automatically.

#3. Webhook Registration

TheVibeCRM automatically registers the required Postgres trigger in your Supabase project using the Supabase Management API. No action is needed in your Supabase Dashboard.

How it works

When you save a listener, TheVibeCRM executes a CREATE TRIGGER statement in your Supabase database via the Management API. The trigger fires on every INSERT and sends a signed HTTP POST to TheVibeCRM. When you delete a listener, the trigger is automatically dropped as well.

Manual setup (fallback) — only needed for legacy connections or if auto-registration fails

If the automatic trigger registration was not available (e.g. the connection was made before the OAuth upgrade), you can set the webhook up manually in your Supabase Dashboard:

Go to Database → Webhooks
Click Create a new webhook
Set Table to the same table configured in the listener, and Events to INSERT only
Set Type to HTTP Request, Method to POST, and paste the Webhook URL shown in the listener panel
Add header x-webhook-secret with the secret shown in the listener panel

webhook-url — text

https://app.thevibecrm.com/api/webhooks/supabase/{listenerId}

#4. Test the Integration

Insert a new row into your Supabase table. Within seconds, a new lead should appear in your selected pipeline stage.

#Manual Sync

If you prefer batch imports instead of real-time:

Go to Project Settings → Integrations → Supabase
Select a listener and click Sync Now
The system will pull all new rows since the last sync (based on created_at timestamp)

#How It Works

Connection flow

oauth-flow — text

User clicks "Connect with Supabase"
  → Redirected to api.supabase.com to authorize
  → CRM receives OAuth tokens via callback
  → User selects project
  → Management API fetches project anon key
  → Integration saved as "connected"
  → Postgres trigger auto-created in selected project

Runtime flow (per INSERT)

runtime-flow — text

┌──────────────┐     INSERT event      ┌──────────────────┐     Lead created     ┌─────────────┐
│   Supabase   │ ───────────────────▶  │   TheVibeCRM     │ ──────────────────▶  │  Pipeline   │
│   Database   │   POST webhook with   │   Webhook API    │   Field mapping      │   Stage     │
│  (trigger)   │   x-webhook-secret    │                  │   applied            │             │
└──────────────┘                       └──────────────────┘                      └─────────────┘

A new row is inserted into your Supabase table
The auto-registered Postgres trigger fires an HTTP POST to the TheVibeCRM webhook endpoint
The webhook secret is verified against the stored listener secret
Only INSERT events are processed (updates and deletes are ignored)
Field mappings are applied to translate column values into lead fields
A new lead is created in the target pipeline stage

#Troubleshooting

Issue	Solution
`?error=supabase_auth_denied` in URL	OAuth authorization was cancelled. Click Connect with Supabase again and approve the permissions.
`?error=supabase_auth_failed` in URL	Token exchange failed. Verify that your OAuth app is published in Supabase (Organization Settings → OAuth Apps) and that the client credentials in your environment are correct.
`?error=supabase_auth_expired` in URL	The OAuth session timed out (10-minute window). Click Connect with Supabase again and complete the flow without navigating away.
"Invalid webhook secret" (401)	Ensure the `x-webhook-secret` header matches exactly (only relevant for manually configured webhooks)
"Listener not found" (404)	Verify the listener ID in the URL is correct
"Missing required fields" (422)	Both `name` and `email` must be mapped to non-empty columns
"Listener is inactive" (400)	Re-enable the listener in the dashboard