by @must_be_ash

Architecture – Webhooks

Understanding real-time event handling and external service notifications

What Are Webhooks?

Webhooks are like notifications from other services. Instead of your app constantly asking "Did anything happen?", webhooks let other services knock on your door and say "Hey, something happened!"

Real-world example:

When someone pays for your product via Stripe, Stripe immediately sends a webhook to your app saying "Payment successful!" so you can unlock their access right away.

When You Need Webhooks

You use webhooks when your app needs to react immediately to something that happens outside your app:

💳 Payment Processing

When someone pays for something:

  • Stripe webhook: "Payment completed" → Unlock user access
  • PayPal webhook: "Subscription renewed" → Update database
  • Coinbase webhook: "Crypto payment received" → Confirm transaction

📁 File Processing

When files are uploaded or processed:

  • AWS S3 webhook: "File uploaded" → Start processing
  • Cloudinary webhook: "Image optimized" → Update image URLs
  • PDF processing service: "Document ready" → Notify user

📝 Form Submissions

When users submit forms or data:

  • Typeform webhook: "Survey completed" → Add to database
  • Mailchimp webhook: "User subscribed" → Send welcome email
  • Contact form: "New message" → Notify admin

⛓️ Blockchain Events

When something happens on the blockchain:

  • Alchemy webhook: "NFT minted" → Update collection
  • Moralis webhook: "Token transfer" → Update wallet balance
  • Custom contract: "Event triggered" → Execute logic

How Webhooks Work

The Simple Process:

  1. You give the service your webhook URL
    Example: https://yourapp.com/api/webhooks/stripe
  2. Something happens on their end
    Example: A payment is processed
  3. They send you a notification
    Example: Stripe sends payment data to your webhook URL
  4. Your app responds immediately
    Example: Update database and send confirmation email

Webhook URL structure:

app/api/webhooks/[service-name]/route.ts

Each service gets its own webhook endpoint for security and organization

Common Webhook Examples

🔷 Stripe Payments

File: /api/webhooks/stripe/route.ts

  • payment_intent.succeeded → Unlock premium features
  • customer.subscription.created → Start subscription
  • invoice.payment_failed → Send payment reminder

📧 Mailchimp Lists

File: /api/webhooks/mailchimp/route.ts

  • subscribe → Send welcome email and update database
  • unsubscribe → Update user preferences
  • cleaned → Remove invalid email addresses

📝 Typeform Surveys

File: /api/webhooks/typeform/route.ts

  • form_response → Save answers and trigger follow-up
  • Custom logic based on specific answers
  • Send personalized responses or recommendations

🔧 GitHub Events

File: /api/webhooks/github/route.ts

  • push → Trigger deployment or build process
  • pull_request → Run automated tests
  • issues → Send notifications to team

Webhook Security

Since webhooks receive data from external services, security is crucial:

Security Best Practices:

🔐 Verify Signatures

Most services send a signature to prove the webhook is really from them

🔒 Use HTTPS

Always use secure connections to protect data in transit

✅ Validate Data

Check that incoming data matches expected formats and values

📝 Log Events

Keep records of webhook events for debugging and monitoring

⚠️ Important:

Never trust webhook data blindly. Always verify the source and validate the content before taking any actions.

Webhook Best Practices

✅ Do This

  • Always verify webhook signatures
  • Handle retries and duplicate events gracefully
  • Respond quickly (under 5 seconds)
  • Use separate endpoints for different services
  • Log all webhook events for debugging

❌ Avoid This

  • Don't perform long-running operations in webhooks
  • Don't ignore signature verification
  • Don't assume webhooks will only be sent once
  • Don't expose sensitive data in webhook responses
  • Don't block webhook execution with slow operations

🎯 Pro Tips

  • Use a queue for heavy processing after webhook receipt
  • Test webhooks locally using tools like ngrok
  • Set up monitoring and alerts for webhook failures
  • Document your webhook endpoints and expected payloads