supabase-webhooks-events
Set up database webhooks, LISTEN/NOTIFY, and event handlers with signature verification in Supabase.
Install
mkdir -p .claude/skills/supabase-webhooks-events && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/4808" && unzip -o skill.zip -d .claude/skills/supabase-webhooks-events && rm skill.zipInstalls to .claude/skills/supabase-webhooks-events
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Implement Supabase database webhooks, pg_net async HTTP, LISTEN/NOTIFY,Key capabilities
- →Implement database webhooks using pg_net
- →Call Edge Functions from PostgreSQL triggers
- →Utilize Postgres LISTEN/NOTIFY for pub/sub
- →Handle Realtime postgres_changes for client-side events
- →Verify HMAC-SHA256 signatures for inbound webhooks
- →Implement idempotency for webhook event handling
How it works
The skill uses database triggers with `pg_net` or `LISTEN/NOTIFY` to send events, and Edge Functions or Realtime for event reception and processing.
Inputs & outputs
When to use supabase-webhooks-events
- →Setting up database webhooks
- →Implementing signature verification
- →Configuring pg_net triggers
- →Handling Realtime event streams
About this skill
Supabase Webhooks and Database Events
Overview
Choose Database Webhooks/pg_net for configured outbound HTTP, LISTEN/NOTIFY for lightweight database notifications, or Realtime Postgres Changes for UI updates. These mechanisms have different durability, authentication, replay and failure contracts. This skill's concrete signed receiver illustrates accepted inbox INGESTION, not complete business processing or exactly-once delivery.
Prerequisites
- A reviewed producer/receiver contract and intended project identity
- Reviewed migrations, endpoint configuration and secret provisioning
- A durable producer event ID/outbox if reliable signed ingestion is required
- An explicitly authorized deployment workflow; reading this skill deploys nothing
Authentication
Native Database Webhooks send the HTTP headers you configure. They do not implicitly generate the custom HMAC protocol below. Do not send a project service-role key to an arbitrary outbound URL as a generic webhook secret. Use a receiver-specific credential or the documented intended gateway identity, kept in an appropriate secret store, with minimal capability and rotation scope.
For the application-owned HMAC example, the sender and receiver BOTH implement the exact raw-byte and timestamp contract. Missing receiver configuration, invalid signature, stale/future timestamp or malformed input is rejected before inbox insertion. Timestamp freshness alone is not durable replay prevention.
The gateway and handler must agree: a JWT-protected Edge Function needs the actual supported gateway authentication identity; an HMAC-only endpoint requires a consciously configured dedicated route that permits that sender and enforces HMAC inside the handler. Do not blindly disable JWT checks on other functions or claim that HMAC headers satisfy JWT verification. A receiver's server-only database key is not an outbound sender credential and must never appear in delivery headers.
Instructions
Step 1: Select One Delivery Contract
Inventory the event source, authorized endpoint, payload fields, producer identity,
retries, timeout, dead-letter path and protected evidence. Review any trigger SQL
before applying it. A Database Webhook payload (type, table, record,
old_record) is not automatically the custom signed inbox envelope. The legacy
Database Webhook reference describes transport
mechanics; its SQL alone does not provide this custom signature/outbox guarantee.
Do not connect an unsigned trigger to the signed receiver and weaken verification
to make it pass.
Step 2: Authenticate and Persist an Inbox Record
Use the bounded receiver and explicit inbox schema with the matching sender/verifier. The producer supplies a unique event ID for each distinct event and retains it across retries. The receiver authenticates raw bytes before strict JSON/schema validation, then attempts one unique-key insert. No SELECT-then-side-effect-INSERT sequence and no row-ID/type-derived deduplication key is used.
202 means accepted into the inbox, with processingComplete: false. 409 means the
ID already exists and requires producer-receipt reconciliation, not proof of
completed effects or identical payload. A lost response after commit requires
reconciliation of that SAME ID. Build a separate authorized worker with durable
lease/retry/dead-letter and effect-idempotency semantics before enabling business
actions. No executable business stub is supplied here.
Step 3: Treat Notifications as Hints, Not Durable Work Completion
LISTEN/NOTIFY is not a persistent queue. Its payload size has a strict byte limit; oversized payloads fail rather than being safely truncated. Send minimal IDs and re-read authorized state. Realtime subscriptions similarly need correct user/RLS and publication setup plus reconciliation after reconnect. Do not log changed rows or infer guaranteed event recovery from a successful subscription.
See notification and Realtime mechanics, reviewing authentication, lifecycle cleanup and evidence boundaries for the actual application before adopting any example.
Output
- Explicit transport and authentication contracts, with native/custom boundaries
- Unique producer event IDs and durable accepted-inbox receipts
- Separate worker/retry/reconciliation requirements and unresolved processing state
- Operational evidence without payloads, tokens or secret headers
Error Handling
| Observation | Required check |
|---|---|
| HTTP 401/403 | Match actual gateway and handler authentication; never bypass verification to resolve it |
| Missing HMAC configuration | Fail closed; do not insert or acknowledge acceptance |
| Duplicate event ID | Reconcile durable producer/inbox receipts; do not invent a new ID for the retry |
| Inbox error/timeout | No completed-effects claim; reconcile possible commit before retry |
| Realtime silence | Check identity, policies, publication, connectivity and reconciliation |
| NOTIFY oversize | Reduce to IDs; no truncation guarantee |
Examples
- Signed protocol and request builder: explicit application-owned headers/raw bytes, not a native signing claim.
- Inbox receiver: bounded validation and checked unique insertion, no business completion acknowledgment.
Resources
Next Steps
Review worker authorization, durable delivery/processing receipts, replay horizons and failure recovery before enabling side effects or claiming production readiness.
Prerequisites
Limitations
- →NOTIFY payload truncated if it exceeds 8000 bytes
How it compares
This provides production-ready patterns for event-driven architectures, unlike basic webhook setup.
Compared to similar skills
supabase-webhooks-events side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| supabase-webhooks-events (this skill) | 1 | 4mo | Caution | Advanced |
| local-cluster-manager | 2 | 4mo | Review | Intermediate |
| create-example | 0 | 7mo | Review | Advanced |
| comparing-database-schemas | 1 | 4mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by jeremylongshore
View all by jeremylongshore →You might also like
local-cluster-manager
multigres
Manage local multigres cluster components (multipooler, pgctld, multiorch, multigateway) - start/stop services, view logs, connect with psql, test S3 backups locally
create-example
ormico
Create a new scenario from scratch — guides Phases 1-3 (concept, SCHEMA_DESIGN.md, SCENARIO.md), scaffolds the folder structure, stubs test-data/data-manifest.json, and updates README.md.
comparing-database-schemas
jeremylongshore
Process use when you need to work with schema comparison. This skill provides database schema diff and sync with comprehensive guidance and automation. Trigger with phrases like "compare schemas", "diff databases", or "sync database schemas".
sql-optimization-patterns
wshobson
Master SQL query optimization, indexing strategies, and EXPLAIN analysis to dramatically improve database performance and eliminate slow queries. Use when debugging slow queries, designing database schemas, or optimizing application performance.
drizzle-orm
EpicenterHQ
Drizzle ORM patterns for type branding and custom types. Use when working with Drizzle column definitions, branded types, or custom type conversions.
postgres-patterns
affaan-m
PostgreSQL database patterns for query optimization, schema design, indexing, and security. Based on Supabase best practices.