Sending Webhooks

Sending webhooks with Von involves three key concepts: Events, Endpoints, and Deliveries. This guide covers how they work together.

Events

An event represents something that happened in your application that you want to notify your customers about.

Event Structure

Each event has:

Event Type - A string like order.created or invoice.paid
Payload - The JSON data to send
Idempotency Key - Optional key to prevent duplicates

Event Types

Use dot notation to organize your events: resource.action

Examples:

user.created
order.shipped
payment.failed

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

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

// Send a single event
await von.webhooks.post({
  eventType: "order.created",
  payload: {
    orderId: "ord_123",
    total: 99.99,
    items: ["item_1", "item_2"],
  },
});

// Send with idempotency key
await von.webhooks.post({
  eventType: "payment.completed",
  payload: { paymentId: "pay_456" },
  idempotencyKey: "pay_456_completed",
});

Endpoints

Endpoints are the URLs where Von delivers your webhooks. Each endpoint can be configured with its own retry policy, timeout, and event filters.

urlstringrequired

The URL where webhooks will be delivered. Must be HTTPS in production.

descriptionstring

A human-readable label for this endpoint.

enabledboolean

Whether this endpoint receives webhooks. Defaults to true.

retryCountnumber

Number of retry attempts (0-10). Defaults to 3.

timeoutMsnumber

Request timeout in milliseconds (1000-60000). Defaults to 30000.

eventsstring[]

Event type filters. Supports wildcards like order.*. Empty means all events.

secretstring

Auto-generated HMAC signing secret for this endpoint.

Creating Endpoints

Create endpoints via the SDK or dashboard. Each endpoint gets a unique secret for webhook verification.

Event Filtering

Use the events array to subscribe to specific event types. Wildcards are supported:

order.* - All order events
payment.completed - Only payment completed events

// Create an endpoint
const endpoint = await von.endpoints.post({
  url: "https://your-app.com/webhooks",
  description: "Production webhook endpoint",
  retryCount: 5,
  timeoutMs: 10000,
  events: ["order.*", "payment.completed"],
});

// Update an endpoint
await von.endpoints[endpoint.id].patch({
  enabled: false,
});

// Delete an endpoint
await von.endpoints[endpoint.id].delete();

Deliveries

When you send an event, Von creates a delivery for each matching endpoint. Deliveries track the status of each webhook attempt.

Delivery Status

Status	Description
`pending`	Queued for delivery
`processing`	Currently being delivered
`delivered`	Successfully delivered (2xx response)
`failed`	All retry attempts exhausted

Retry Behavior

When a delivery fails, Von retries with exponential backoff:

First retry: 1 minute
Second retry: 5 minutes
Third retry: 30 minutes
And so on...

Batch Sending

Send multiple events in a single API call for better performance:

await von.webhooks.batch.post({
  events: [
    { eventType: "order.created", payload: { orderId: "ord_1" } },
    { eventType: "order.created", payload: { orderId: "ord_2" } },
    { eventType: "inventory.updated", payload: { sku: "SKU123" } },
  ],
});

Next Steps

Verification - Learn how to verify webhooks on the receiving end
Versioning - Evolve your webhook payloads safely
TypeScript SDK - Full SDK reference