Supabase and Twilio integrate through Supabase Database Webhooks and Edge Functions to send SMS when rows are inserted, updated, or deleted in your Postgres tables, creating an event-driven SMS layer directly on top of your Supabase database without managing any additional servers. This integration is used by development teams building on the Supabase stack who want SMS notifications for new user signups, order state changes, support ticket assignments, and monitoring alerts all driven by Postgres row-level events. The connection uses Supabase Database Webhooks to call a Supabase Edge Function as the target, and the Edge Function calls the Twilio Messages API with row data extracted from the webhook payload.
What You Need Before You Start
Access Supabase Database Webhooks by navigating to your Supabase project dashboard, selecting Database, then Webhooks, and clicking Create a New Webhook, which allows you to target any table and event type such as INSERT, UPDATE, or DELETE and specify the HTTP endpoint that Supabase will call when the event occurs. Create a Supabase Edge Function by installing the Supabase CLI, running supabase functions new twilio-sms-handler from your project directory, and writing the function in TypeScript in the generated supabase/functions/twilio-sms-handler/index.ts file, which runs on Deno and handles the incoming webhook POST from Supabase. Store your Twilio Account SID, Auth Token, and From Number as Supabase Edge Function secrets by running supabase secrets set TWILIO_ACCOUNT_SID=ACxxxx TWILIO_AUTH_TOKEN=your_auth_token TWILIO_FROM_NUMBER=+14155551234, and retrieve them in the Edge Function using Deno.env.get('TWILIO_ACCOUNT_SID'). From Twilio, provision an SMS-capable phone number and complete A2P 10DLC registration before enabling US-bound customer-facing SMS.
Step-by-Step Integration Guide
Write the Supabase Edge Function to handle the Twilio SMS dispatch by importing the serve function from the Deno standard library and writing: serve(async (req) => { const payload = await req.json(); const record = payload.record; const phone = record.phone; if (!phone) return new Response('no phone', { status: 200 }); const accountSid = Deno.env.get('TWILIO_ACCOUNT_SID'); const authToken = Deno.env.get('TWILIO_AUTH_TOKEN'); const fromNumber = Deno.env.get('TWILIO_FROM_NUMBER'); const body = encodeURIComponent('Hi ' + record.first_name + ', your request has been received. Reference: ' + record.id); const params = 'To=' + encodeURIComponent(phone) + '&From=' + encodeURIComponent(fromNumber) + '&Body=' + body; const response = await fetch('https://api.twilio.com/2010-04-01/Accounts/' + accountSid + '/Messages.json', { method: 'POST', headers: { 'Authorization': 'Basic ' + btoa(accountSid + ':' + authToken), 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); return new Response(JSON.stringify({ status: response.status }), { status: 200 }); }). Deploy the Edge Function by running supabase functions deploy twilio-sms-handler --no-verify-jwt from your project directory, then copy the deployed function URL from the Supabase dashboard under Edge Functions. Configure the Supabase Database Webhook by returning to Database, then Webhooks, creating a webhook targeting your table such as orders, selecting the INSERT event, setting the HTTP endpoint to your deployed Edge Function URL, and adding the Authorization header with value Bearer {supabaseServiceRoleKey} if you protect the Edge Function endpoint. Test the integration by inserting a test row into your table directly in the Supabase Table Editor and checking the Twilio Console message log to confirm the SMS was dispatched.
Common Issues and How to Fix Them
Supabase Database Webhooks deliver the payload with both the old_record and record fields, where record contains the new row data for INSERT and UPDATE events and old_record contains the previous values for UPDATE and DELETE events, but accessing the wrong field in your Edge Function causes the SMS to be composed with null or empty values. Verify your Edge Function reads payload.record for INSERT events and both payload.old_record and payload.record for UPDATE events so you can compute the diff and only send SMS when the relevant field has actually changed. The Supabase Edge Function receives the database webhook payload but Supabase does not sign the request with a verifiable HMAC signature by default, making your Edge Function endpoint vulnerable to spoofed requests. Add a shared secret to the Supabase webhook configuration as a custom HTTP header named X-Webhook-Secret with a random value, read that header in your Edge Function using req.headers.get('X-Webhook-Secret'), and return a 401 response if the value does not match the stored secret. Supabase Database Webhooks time out after 5 seconds, and if your Edge Function takes longer to call the Twilio API and respond, Supabase marks the delivery as failed and may retry, causing duplicate SMS. Return the 200 response to Supabase immediately after parsing the payload and dispatch the Twilio API call in a non-blocking promise chain using EdgeRuntime.waitUntil or simply fire the fetch without awaiting the full result before sending the response.
How to Get More from This Integration
Build a Supabase Realtime SMS alert by creating a Postgres function and trigger that calls pg_notify with a channel name and a JSON payload when a row changes, then listening to that channel from a lightweight Node.js server using the Supabase Realtime client subscription to the postgres_changes event, and dispatching a Twilio SMS from the server-side listener, enabling more complex conditional logic than a webhook alone can provide. Add a Twilio Verify OTP flow for Supabase Auth by creating a Supabase Edge Function that accepts a phone number, calls the Twilio Verify API, and returns a session token, then creating a second Edge Function that accepts the OTP code and phone, verifies with Twilio, and on success creates a Supabase Auth user via the Admin API using supabase.auth.admin.createUser, bridging Twilio's OTP verification with Supabase's user management. Create an SMS reminder for Supabase-stored appointments by writing a Postgres function that queries your appointments table for rows where appointment_time is between now() and now() + interval '24 hours' and reminder_sent is false, then calling your Edge Function via pg_net HTTP request (available in Supabase via the pg_net extension), and marking reminder_sent as true in the same transaction, enabling a fully database-driven reminder system. Extend the integration with Supabase Row Level Security by adding a policy on your sms_log table that allows only the service role to insert rows, and logging every Twilio API response including the message SID, status, and timestamp to the sms_log table from within the Edge Function for a complete audit trail of all SMS dispatched from your Supabase application.
Conclusion
Supabase Database Webhooks and Twilio together create a serverless SMS notification layer driven directly by your Postgres table events, without any additional infrastructure beyond a Supabase Edge Function. Reach out to Telphi Consulting to design and implement a Supabase Twilio SMS integration for your application.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.