Getting started

This guide adds a webhook endpoint to a Layeron backend, stores the provider secret in Secrets, and handles one event type.

Create the secret

Use a Secrets reference for verification keys:

import { secret } from "@layeron/core"

const stripeSecret = secret("STRIPE_WEBHOOK_SECRET")

Set the secret value for each environment with the Layeron CLI or dashboard.

Add a Stripe webhook

webhooks.stripe(...) configures the Stripe signature header, timestamp tolerance, and signed payload format for you:

import { backend, secret } from "@layeron/core"
import { webhooks } from "@layeron/modules"

const app = backend()

const stripe = webhooks.stripe({
  path: "/webhooks/stripe",
  secret: secret("STRIPE_WEBHOOK_SECRET"),
  on: {
    "checkout.session.completed": async (event) => {
      const session = event.payload

      await fulfillCheckout(session)
    },
    "invoice.paid": async (event) => {
      await markInvoicePaid(event.payload)
    },
  },
})

app.use(stripe)

After deploy, configure the provider to call:

https://api.example.com/webhooks/stripe

Use your deployed app domain in place of api.example.com.

Add a custom vendor webhook

Use webhooks.custom(...) when the provider has its own signature format:

const vendor = webhooks.custom({
  name: "vendor",
  path: "/webhooks/vendor",
  signature: {
    header: "x-vendor-signature",
    algorithm: "hmac-sha256",
    encoding: "hex",
    secret: secret("VENDOR_WEBHOOK_SECRET"),
    signedPayload: "rawBody",
  },
  dedupe: {
    key: "body.event_id",
    ttl: "7d",
  },
  handler: async (event) => {
    await processVendorEvent(event.payload)
  },
})

app.use(vendor)

Read recent events

Every webhook module exposes events helpers:

const recent = await vendor.events.list({
  direction: "inbound",
  limit: 25,
})

const failed = await vendor.events.list({
  status: "failed",
})

Use these helpers for admin screens, support tools, and manual replay flows.

Replay an event

await vendor.events.replay("whevt_123")

Replay runs the event through the same handler path and records the replay.

Next Steps

• Inbound handlers: Use one handler, route by event type, deduplicate provider retries, and control return behavior.
• Signatures and secrets: Verify Stripe, HMAC, signed payload, unusual, and custom signatures.
• Delivery settings: Configure inbound retry behavior, outbound retries, dedupe windows, and observability.
• Paths and domains: Place endpoints by path or host and name them consistently.
• Events and replay: List, inspect, replay, and expose admin retry routes for webhook records.