> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Define an HTTP action in convex/http.ts">
    Listens at `/api/{provider}-webhook`.
  </Step>

  <Step title="Verify the signature">
    Use the provider's recommended verification method. Reject if invalid.
  </Step>

  <Step title="Parse the event payload">
    JSON; use the provider's SDK to type-narrow.
  </Step>

  <Step title="Run the appropriate mutation or action">
    Update your DB / send notifications / etc.
  </Step>

  <Step title="Return 200 quickly">
    If the response takes too long, providers will retry. Defer slow work to a [scheduled function](/convex/scheduled-functions).
  </Step>
</Steps>

## Foundation prompt

```text theme={null}
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

<Tip>
  **Always verify signatures.** Without verification, anyone who finds your URL can fake events.
</Tip>

<Tip>
  **Use idempotency keys.** Providers re-send events if they don't get a 200 quickly. Track event IDs to avoid double-processing.
</Tip>

## Related

<CardGroup cols={3}>
  <Card title="Webhooks SDK helpers" icon="code" href="/api-reference/sdks/webhooks">
    Verification helpers.
  </Card>

  <Card title="Stripe integration" icon="credit-card" href="/integrations/stripe">
    A specific implementation.
  </Card>

  <Card title="HTTP actions" icon="zap" href="/convex/actions">
    The function type webhooks live in.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.