Webhooks

Receive events from third-party services securely. The general pattern.

The pattern for any service that pushes events to your app — Stripe, Resend, Twilio, GitHub.

Time: ~20 min per integration. Difficulty: Intermediate.

The pattern

1. Define an HTTP action in convex/http.ts

   Listens at /api/{provider}-webhook.

2. Verify the signature

   Use the provider’s recommended verification method. Reject if invalid.

3. Parse the event payload

   JSON; use the provider’s SDK to type-narrow.

4. Run the appropriate mutation or action

   Update your DB / send notifications / etc.

5. Return 200 quickly

   If the response takes too long, providers will retry. Defer slow work to a scheduled function.

Foundation prompt

Add a webhook endpoint for Stripe. Listen at /api/stripe-webhook. Verify
signature with STRIPE_WEBHOOK_SECRET. Handle these events:
- checkout.session.completed → mark user's plan as the new tier
- customer.subscription.deleted → downgrade user to Free
- invoice.payment_failed → mark workspace as past_due

Tips

Always verify signatures. Without verification, anyone who finds your URL can fake events.

Use idempotency keys. Providers re-send events if they don’t get a 200 quickly. Track event IDs to avoid double-processing.

Related

Webhooks SDK helpers

Verification helpers.

Stripe integration

A specific implementation.

HTTP actions

The function type webhooks live in.