Quickstart

Send your first event in 5 minutes. You'll need an API key from the admin panel — see About for how to get one for the demo.

1. Create a subscription

A subscription is a URL that will receive events matching a filter.

curl

curl -X POST https://api.webhook-relay.dcsuniverse.com/v1/subscriptions \
  -H "Authorization: Bearer whk_live_..." \
  -d '{
    "name": "my receiver",
    "url": "https://your-app.example.com/webhooks",
    "event_filter": "order.*"
  }'

The response includes a signing_secret — store it. The secret is the input to the HMAC verifier; you cannot retrieve it later, only rotate it.

2. Ingest an event

Anything you POST to /v1/events with a matching type will be fanned out to your subscription.

curl

curl -X POST https://api.webhook-relay.dcsuniverse.com/v1/events \
  -H "Authorization: Bearer whk_live_..." \
  -H "Idempotency-Key: order-42-created" \
  -d '{
    "type": "order.created",
    "payload": {"order_id": 42, "total_cents": 9900}
  }'

The response is a 202 with the event ID. Delivery is asynchronous.

3. Verify on your receiver

Every outbound POST carries an X-Webhook-Signature header. Verify it with the SDK helper for your language.

typescript

import { verifySignature } from "@philiprehberger/webhook-relay-client";

export async function POST(request: Request) {
  const body = await request.text();   // raw bytes — DO NOT JSON.parse first
  const ok = verifySignature(
    process.env.WEBHOOK_SECRET,
    body,
    request.headers.get("x-webhook-signature"),
  );
  if (!ok) return new Response("Bad signature", { status: 400 });

  const event = JSON.parse(body);
  // ... handle event
  return new Response("ok");
}

That's the whole loop. From here, browse the signing concept for the wire format details, or hit the try-it console to fire calls without leaving the docs.