playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-webhooks-events

supabase-webhooks-events skill

/plugins/saas-packs/supabase-pack/skills/supabase-webhooks-events

This skill helps you secure and process Supabase webhooks by implementing signature verification, event handlers, and idempotency for reliable notifications.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-webhooks-events

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.6 KB
---
name: supabase-webhooks-events
description: |
  Implement Supabase webhook signature validation and event handling.
  Use when setting up webhook endpoints, implementing signature verification,
  or handling Supabase event notifications securely.
  Trigger with phrases like "supabase webhook", "supabase events",
  "supabase webhook signature", "handle supabase events", "supabase notifications".
allowed-tools: Read, Write, Edit, Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Webhooks Events

## Prerequisites
- Supabase webhook secret configured
- HTTPS endpoint accessible from internet
- Understanding of cryptographic signatures
- Redis or database for idempotency (optional)

## Instructions

### Step 1: Register Webhook Endpoint
Configure your webhook URL in the Supabase dashboard.

### Step 2: Implement Signature Verification
Use the signature verification code to validate incoming webhooks.

### Step 3: Handle Events
Implement handlers for each event type your application needs.

### Step 4: Add Idempotency
Prevent duplicate processing with event ID tracking.

## Output
- Secure webhook endpoint
- Signature validation enabled
- Event handlers implemented
- Replay attack protection active

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Supabase Webhooks Guide](https://supabase.com/docs/webhooks)
- [Webhook Security Best Practices](https://supabase.com/docs/webhooks/security)

Overview

This skill implements Supabase webhook signature validation and secure event handling for Python services. It provides a clear pattern for validating incoming requests, wiring event handlers, and preventing replay or duplicate processing. Use it to harden webhook endpoints and reliably process Supabase event notifications.

How this skill works

The skill verifies the HMAC signature attached to each incoming Supabase webhook request against a configured webhook secret. After validation, it parses the event payload and dispatches to typed handlers for each event name. Optional idempotency tracking (Redis or database) ensures the same event ID is not processed more than once.

When to use it

  • Setting up a new Supabase webhook endpoint for production
  • Adding signature verification to an existing webhook handler
  • Handling Supabase insert/update/delete events securely
  • Protecting endpoints from replay or forged requests
  • Implementing idempotent processing for event-driven workflows

Best practices

  • Store the Supabase webhook secret in a secure environment variable or secrets manager
  • Always verify the HMAC signature before reading or acting on the payload
  • Record each event ID in Redis or a durable store to enforce idempotency
  • Use HTTPS endpoints and strict request time-window checks to reduce replay risks
  • Log validation failures and metric them for monitoring and alerting

Example use cases

  • A serverless function that validates Supabase signatures then triggers downstream jobs
  • A microservice that subscribes to DB changes and updates search indexes once per event
  • An API that rejects unsigned or expired requests and records failed attempts
  • A background worker that consumes verified events and marks event IDs as processed
  • A dashboard that shows webhook delivery and verification metrics for audits

FAQ

What if an event arrives without a signature?

Reject the request with an HTTP 400/401 and log the attempt. Treat unsigned requests as malicious.

How do I prevent duplicate processing?

Store the Supabase-provided event ID in Redis or your database with a TTL. Skip processing when the ID already exists.