Receiving Webhooks

Von's inbound feature lets you receive webhooks from third-party services like Stripe, GitHub, or Shopify. Von queues and forwards these webhooks to your application, ensuring reliable delivery even if your server is temporarily down.

Why Use Inbound?

When receiving webhooks directly, your server must be:

• Always available
• Fast enough to respond within timeout limits
• Able to handle retries from the provider

With Von inbound, you get:

• Queueing - Webhooks are stored if your server is down
• Retries - Automatic retries with exponential backoff
• Monitoring - Track all incoming webhooks in one place
• Circuit breaker - Protects your server from being overwhelmed

How It Works

Third-party → Von Inbound URL → Queue → Your Application
(Stripe)       (always available)       (can be down)

1. Configure the third-party service to send webhooks to your Von inbound URL
2. Von receives and queues the webhook
3. Von forwards to your application with retries
4. Your application processes the webhook

Creating Inbound Endpoints

import { Von } from "@usevon/sdk";

const von = new Von({
  apiKey: process.env.VON_API_KEY,
});

// Create an inbound endpoint
const inbound = await von.inbound.post({
  name: "Stripe Payments",
  provider: "stripe",
  forwardUrl: "https://your-app.com/webhooks/stripe",
});

console.log("Inbound URL:", inbound.url);
// Use this URL in Stripe's webhook settings

Managing Inbound Endpoints

// List all inbound endpoints
const { data: inbounds } = await von.inbound.get();

// Get a specific inbound endpoint
const inbound = await von.inbound["inb_123"].get();

// Update an inbound endpoint
await von.inbound["inb_123"].patch({
  forwardUrl: "https://new-url.com/webhooks",
  enabled: true,
});

// Delete an inbound endpoint
await von.inbound["inb_123"].delete();

Forwarded Request Format

When Von forwards an inbound webhook to your application, it includes:

The request body is forwarded exactly as received from the provider.

Verifying Provider Signatures

For providers like Stripe that sign their webhooks, you should still verify the original signature:

import Stripe from "stripe";

app.post("/webhooks/stripe", async (req, res) => {
  const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

  // Verify Stripe's signature
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers["x-von-original-stripe-signature"],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  // Process the event
  switch (event.type) {
    case "payment_intent.succeeded":
      // Handle successful payment
      break;
  }

  res.json({ received: true });
});

Circuit Breaker

If your forward URL fails repeatedly, Von's circuit breaker activates:

1. Closed - Normal operation, webhooks forwarded
2. Open - After 5 consecutive failures, forwarding paused
3. Half-Open - After 5 minutes, Von tests with one request
4. Closed - If test succeeds, normal operation resumes

This protects your server from being overwhelmed during outages.

Next Steps

• Verification - Verify webhook signatures
• CLI - Use tunnels for local development