Svix

Svix is a hosted webhook delivery service and the alternative to the built-in driver behind webhooks. webhooks.emit() hands each delivery to Svix, which signs it per Standard Webhooks and retries it. Pick it when you send webhooks to many customers and want delivery run as a service.

webhooks:
  driver: svix

Before you start

1. Create a Svix account and an environment for development and one for production.
2. Create an API key for each environment and store it in your secrets manager.
3. Decide how your customers' endpoints map to Svix applications. How MainSDK maps an emit() endpoint onto Svix is not specified yet.

Configure

webhooks:
  driver: svix                 # [to be decided] how the driver takes its API key; suggested name SVIX_API_KEY
  retries: { max: 8, window: 24h }

Use it

import { webhooks } from "mainsdk";

export async function notifyPartner(order: { id: string; partnerUrl: string }) {
  return webhooks.emit(
    order.partnerUrl,                                         // [to be decided] endpoint type
    { type: "order.shipped", data: { orderId: order.id } },   // [to be decided] event shape
    { idempotencyKey: `order.shipped:${order.id}` },
  );
}

Local development and testing

Use the builtin driver in development. In tests, createTestApp() from @mainsdk/testing runs webhooks on a fake, chaos.on("webhooks", { outage: true }) shows retries, and clock.advance() moves through the retry window.

What MainSDK adds on top

• Outbound webhooks signed per Standard Webhooks.
• Idempotency keys, so a retried emit() delivers once.
• webhooks.receive() for inbound calls stays the same whichever driver sends.

See Webhooks.

Limits and notes

• The driver comes with the webhooks-jobs spec (phase 1).
• Payloads pass through Svix; check its data region fits yours (US, EU or India).

Swap to or from it

webhooks:
  driver: svix   # was builtin

Outbound webhooks are stateless, so mainsdk swap needs no data migration. Whether the delivery log moves with the driver is not stated yet.

FAQ

Do receivers need to change anything? No. Deliveries are Standard Webhooks either way, so receivers verify them with any standard library.

Is Svix used for inbound webhooks? No. The driver is for emit(); receive() verification runs in MainSDK.

Next

• Webhooks and Events and background jobs
• Inngest

Open questions