Supabase as a Shopify Side-Car Database: Webhooks and RLS
No7 Engineering Team
Growth Architecture Unit

A side-car database is a second database that runs next to Shopify and holds the data Shopify was not designed to model: deep relational records, high-write logs, custom application state. Shopify stays the system of record for products, orders and checkout; the side-car keeps everything else and stays in sync through webhooks. This guide shows how to build that with Supabase, using Supabase's and Shopify's own documentation for every rule. For product search on the same stack, see our pgvector product search guide.
What data belongs in Supabase and what stays in Shopify?
Keep anything Shopify uses to sell in Shopify; move data that is relational, high-volume or app-specific to the side-car.
| Data | Where it lives | Why |
|---|---|---|
| Products, variants, prices, inventory | Shopify | Checkout, catalogue and sales channels read them directly |
| Product specs shown on the page | Shopify metafields and metaobjects | Themes and the Storefront API can read them without another service |
| Orders and customers | Shopify, with a copy in Supabase for reporting | Shopify is the source of truth; the copy is for joins and analysis |
| Relational app data (warranty registrations, B2B account hierarchies, bookings) | Supabase | Foreign keys, transactions and SQL queries across tables |
| Webhook log and audit trail | Supabase | High write volume, and you need it to replay or reconcile |
How do you receive Shopify webhooks in Supabase?
With a Supabase Edge Function. Supabase describes Edge Functions as server-side TypeScript functions, developed with Deno and distributed globally, and lists listening to webhooks as one of their uses. The function has three jobs, all taken from Shopify's webhook verification guide:
- Verify the HMAC. Shopify sends a base64-encoded HMAC-SHA256 signature in the
X-Shopify-Hmac-SHA256header, computed from your app's client secret and the raw request body. Read the body as raw text before parsing it, or the signature will not match. - Skip duplicates. Shopify says the same webhook can arrive more than once, for example after a timeout or retry, and recommends idempotent processing or deduplicating on the
X-Shopify-Webhook-Idheader. - Respond fast. Shopify's guidance is to acknowledge with a 2xx status as quickly as possible and process the payload asynchronously.
A minimal function that does all three, storing each delivery once in a log table:
// supabase/functions/shopify-webhooks/index.ts
import { createClient } from 'npm:@supabase/supabase-js@2';
const supabase = createClient(
Deno.env.get('SUPABASE_URL')!,
Deno.env.get('SUPABASE_SECRET_KEY')!, // server-only key, never shipped to a browser
);
const encoder = new TextEncoder();
async function verifyShopifyHmac(body: string, header: string) {
try {
const key = await crypto.subtle.importKey(
'raw',
encoder.encode(Deno.env.get('SHOPIFY_CLIENT_SECRET')!),
{ name: 'HMAC', hash: 'SHA-256' },
false,
['verify'],
);
const signature = Uint8Array.from(atob(header), (c) => c.charCodeAt(0));
return await crypto.subtle.verify('HMAC', key, signature, encoder.encode(body));
} catch {
return false;
}
}
Deno.serve(async (req) => {
const body = await req.text(); // raw body, before any JSON parsing
const hmac = req.headers.get('X-Shopify-Hmac-SHA256') ?? '';
if (!(await verifyShopifyHmac(body, hmac))) {
return new Response('Invalid signature', { status: 401 });
}
const { error } = await supabase.from('shopify_webhooks').insert({
webhook_id: req.headers.get('X-Shopify-Webhook-Id'),
topic: req.headers.get('X-Shopify-Topic'),
shop_domain: req.headers.get('X-Shopify-Shop-Domain'),
payload: JSON.parse(body),
});
// 23505 is Postgres unique_violation: this delivery is already stored.
if (error && error.code !== '23505') {
return new Response('Storage error', { status: 500 });
}
return new Response('OK', { status: 200 });
});The table behind it gives webhook_id a unique constraint, so a duplicate delivery fails the insert and is acknowledged without being processed twice:
create table public.shopify_webhooks (
id bigint generated always as identity primary key,
webhook_id text not null unique,
topic text not null,
shop_domain text not null,
payload jsonb not null,
received_at timestamptz not null default now(),
processed_at timestamptz
);
-- RLS on with no policies: only the server-side secret key can read or write.
alter table public.shopify_webhooks enable row level security;A separate job then reads unprocessed rows, applies them to your application tables and sets processed_at. Keeping storage and processing apart is what lets the function answer Shopify immediately.
How does Row Level Security protect Shopify data in Supabase?
Row Level Security decides what each key can see, so choose the key by where the code runs. Supabase's API keys guide is direct about it: the publishable key is for anything you ship, such as a browser or mobile app, and only reaches what Row Level Security allows; the secret key is for code you control, such as a server or Edge Function, and it bypasses Row Level Security, so it must never leave your control.
In practice that gives two rules for a Shopify side-car:
- Webhook and sync tables have RLS enabled and no client policies, so only Edge Functions and jobs using the secret key touch them.
- Tables a storefront reads (a customer's warranty registrations, say) have RLS policies that limit each signed-in user to their own rows, and the storefront uses the publishable key. See Supabase's Row Level Security guide for policy syntax.
How do you push live updates to the storefront?
Supabase Realtime can stream database changes to subscribed clients. Its Postgres Changes guide shows a table secured with Row Level Security and a client subscribing to its changes through the Supabase client library. Use it for data that lives in the side-car, such as a booking slot or a warranty status. Inventory that Shopify owns should still be read from Shopify, because checkout uses Shopify's numbers, not the copy.
What happens when webhooks fail or drift?
They will, so plan for it. Shopify's webhook troubleshooting guide says failed webhook calls are retried up to eight times in a four-hour period, and if failures persist the subscription is removed. After that, the side-car silently stops receiving updates. Three safeguards keep it honest:
- Monitor deliveries. Shopify's Dev Dashboard shows delivery logs for the past seven days and a delivery metrics report; treat a removed subscription as an incident.
- Reconcile on a schedule. Run a nightly job that reads changed records from the Shopify Admin API and corrects any drift, so a missed webhook costs hours, not weeks.
- Make processing idempotent. Shopify recommends it because duplicates happen; apply each payload as the current state of the record rather than as a change to add on top.
When is a side-car database worth it?
When the data has relationships or volume that metafields and metaobjects cannot serve without a lot of Admin API calls: account hierarchies, bookings, registrations, audit logs, or analytics that join orders with other systems. When the data is product content that a theme displays, keep it in Shopify. The side-car adds a second system to monitor and secure, so it should hold data that genuinely needs it.
What to do next
List the data your custom features need, mark which of it Shopify already models, and put only the rest in Supabase. Start with the webhook log table and the Edge Function above, then add the reconciliation job before you depend on the data. If you are building this as part of a custom app, our Shopify app development team can help, and for headless builds see our headless Shopify development page.
Frequently Asked Questions
The questions buyers and engineers ask us most about this topic.
What is a side-car database for Shopify?
A side-car database runs next to Shopify and holds data Shopify was not designed to model, such as relational app records, account hierarchies, bookings and audit logs. Shopify remains the system of record for products, orders and checkout, and the side-car stays in sync through webhooks plus a scheduled reconciliation job.
How do I verify Shopify webhooks in a Supabase Edge Function?
Read the request body as raw text, compute HMAC-SHA256 over it with your app's client secret, and compare the base64 result with the X-Shopify-Hmac-SHA256 header. Reject the request if it does not match. Shopify's guide says to verify before processing and to use the raw body, not parsed JSON.
How do I stop duplicate Shopify webhooks being processed twice?
Shopify says the same webhook can arrive more than once, for example after a timeout or retry. Make processing idempotent, or store the X-Shopify-Webhook-Id header in a column with a unique constraint and skip any delivery whose ID is already stored.
What happens if my Shopify webhook endpoint keeps failing?
Shopify retries failed webhook calls up to eight times in a four-hour period, and if failures persist the subscription is removed. Monitor delivery logs in the Dev Dashboard and run a scheduled reconciliation job against the Admin API so missed webhooks are corrected.
Which Supabase key should a Shopify storefront use?
The publishable key. Supabase says the publishable key is for anything you ship, such as a browser or mobile app, and only reaches what Row Level Security allows. The secret key bypasses Row Level Security and must stay in code you control, such as Edge Functions and server jobs.
Should I store Shopify inventory in Supabase?
Keep inventory in Shopify as the source of truth, because checkout uses Shopify's numbers. A copy in Supabase is fine for reporting and joins, but read live stock for buying decisions from Shopify. Use Supabase Realtime for data that lives in the side-car, such as booking slots.
Are Supabase Edge Functions suitable for Shopify webhooks?
Yes. Supabase describes Edge Functions as server-side TypeScript functions built with Deno and distributed globally, and lists listening to webhooks as a use. Store each delivery and respond with a 2xx quickly, then process it in a separate job, as Shopify recommends.