How it works

Developer Guide

The webhook service acts as a reliable relay between your app and your clients. Instead of delivering webhooks directly from your machine, you push events here and vibey handles delivery, retries, and signing — from a stable, always-on domain.

Your App

Running locally or behind a vibey tunnel, your app pushes events via a single API call

→

webhooks.vibey.cloud

Receives the event, signs the payload, and delivers it to all subscribed endpoints with automatic retries

→

Your Clients

Receive webhooks at their endpoint URLs from a stable domain — even if your machine goes offline

{/* ── Quick Start ─────────────────────────── */}

Quick start — send your first webhook

Add an endpoint — Go to the Endpoints tab and add your client's webhook URL (e.g. https://their-server.com/webhook)

Define event types — Go to Event Catalog and create types like order.created or payment.completed

Push events from your app — When something happens in your app, fire a POST:

{`curl -X POST ${baseUrl}/app/${appUid}/msg/ \\
  -H "Authorization: Bearer ${token}" \\
  -H "Content-Type: application/json" \\
  -d '{"eventType":"order.created","payload":{"orderId":"abc-123","amount":99.99}}'`}

Monitor delivery — Check the Logs and Activity tabs to see delivery status, retry attempts, and inspect payloads

{/* ── API Authentication ─────────────────────────── */}

API authentication & sending messages

All API calls require a Bearer token in the Authorization header. Your credentials are available via the API Credentials button above.

Base URL

{baseUrl}

Send a message (webhook event)

{`POST /app/${appUid}/msg/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "eventType": "user.created",
  "payload": {
"userId": "usr_abc123",
"email": "alice@example.com",
"plan": "pro"
  },
  "channels": ["tenant_42"]     // optional: route to specific endpoints
}`}

The eventType determines which endpoints receive the message (only those subscribed to this type). The payload is the JSON body delivered to each endpoint. Optionally, channels further scopes delivery to endpoints listening on those channels.

List endpoints

{`GET /app/${appUid}/endpoint/
Authorization: Bearer ${token}`}

Create an endpoint

{`POST /app/${appUid}/endpoint/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "url": "https://client.example.com/webhook",
  "description": "Acme Corp production",
  "filterTypes": ["order.created", "order.updated"],
  "channels": ["tenant_42"],
  "rateLimit": 100
}`}

All fields except url are optional. Use filterTypes to restrict which event types this endpoint receives. Use channels to scope to specific message channels. Use rateLimit to cap deliveries per second.

{/* ── Endpoints ─────────────────────────── */}

Endpoints — configuration & management

An endpoint is a URL where webhooks are delivered. Each of your clients registers one or more endpoints. You can configure per-endpoint settings:

{[ ['Event Type Filtering', 'Only receive specific event types (e.g. order.* events). Configured when creating or editing an endpoint.'], ['Channels', 'Route messages to specific endpoints by channel tag. Useful for multi-tenant setups where each tenant has their own endpoint.'], ['Rate Limiting', 'Cap the number of deliveries per second to avoid overwhelming the client\'s server.'], ['Custom Headers', 'Add headers like API keys or Basic Auth credentials, sent with every delivery to that endpoint.'], ].map(([title, desc]) => (

{title}

{desc}

))}

Endpoint lifecycle

Endpoints start as Active. {' '}You can manually disable/enable them from the endpoint detail view. {' '}If an endpoint fails continuously for 5 consecutive days, it is {' '}automatically disabled to prevent wasting resources. {' '}Re-enable it from the endpoint menu and use Recover Failed to retry missed messages.

Update an endpoint

{`PATCH /app/${appUid}/endpoint/{ENDPOINT_ID}/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "url": "https://new-url.example.com/webhook",
  "description": "Updated description",
  "filterTypes": ["order.created"],
  "rateLimit": 50,
  "disabled": false
}`}

{/* ── Event Types ─────────────────────────── */}

Event types — organizing your webhook events

Event types categorize your webhook messages. Use dot-notation to group them (e.g. order.created, order.updated, payment.failed). Define them in the Event Catalog tab before sending messages.

How the Event Catalog works behind the scenes

Under the hood, all event types live in a shared global registry powered by Svix. {' '}When you create an event type, it is tagged with your app identity so the system knows who owns it.

{[ ['Mine (default)', 'Shows only event types you created. Each type is tagged with your app UID, so your catalog stays clean and relevant to your project.'], ['All', 'Shows every event type across all users. Useful for discovering existing types or reusing a shared schema — any user can subscribe their endpoints to any event type.'], ].map(([title, desc]) => (

{title}

{desc}

))}

Why shared? Event types define the schema of events your system can emit — they're not secrets. {' '}Sharing them means multiple apps can interoperate on the same event vocabulary without duplicating definitions. {' '}Your endpoints, messages, and delivery logs remain completely private to your app.

Create an event type

{`POST /event-type/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "name": "order.created",
  "description": "Fired when a new order is placed"
}`}

Endpoints can subscribe to specific event types via filterTypes. {' '}If an endpoint has no filter, it receives all event types.

Each event type can also have a custom retry schedule — see the Retry Policy section below.

{/* ── Retry Policy ─────────────────────────── */}

Retry policy — automatic retries & error handling

When a webhook delivery fails (non-2xx response or no response within 15 seconds), the message is automatically retried with exponential backoff. Any HTTP status outside 200–299, including 3xx redirects, counts as a failure.

Default retry schedule

{DEFAULT_RETRY_SCHEDULE.map((s, i) => ( React.createElement(React.Fragment, {key: i}, i > 0 && React.createElement('span', {style:{color:'var(--text-dim)',fontSize:10}}, '→'), React.createElement('span', {style:{fontSize:11,padding:'3px 8px',borderRadius:6,background:'rgba(124,92,252,0.12)',color:'var(--accent)',fontWeight:600,fontFamily:'monospace'}}, formatRetryInterval(s)) ) ))}

That's 7 retry attempts over approximately 27 hours. After all retries are exhausted, the message is marked as Failed.

Per-event-type retry schedules

You can override the default schedule for specific event types in the Event Catalog tab. Each event type card has a Retry Schedule editor with preset options:

{[ ['Aggressive', '2s → 10s → 30s → 2m → 5m', '5 retries, ~8 minutes total. For time-sensitive events.'], ['Standard', '5s → 5m → 30m → 2h → 5h → 10h → 10h', '7 retries, ~27 hours. The default schedule.'], ['Relaxed', '1m → 10m → 1h → 4h → 12h → 24h', '6 retries, ~41 hours. For non-urgent events.'], ].map(([name, schedule, desc]) => (

{name}

{schedule}

{desc}

))}

You can also define a fully custom schedule by entering comma-separated intervals in seconds. For example, 10, 60, 600, 3600 retries at 10s, 1m, 10m, and 1h.

Via API

{`# Set a custom retry schedule for an event type
PUT /event-type/order.created/retry-schedule/
Authorization: Bearer ${token}
Content-Type: application/json

{"retrySchedule": [10, 60, 600, 3600]}

# Reset to the default schedule
PUT /event-type/order.created/retry-schedule/
{"retrySchedule": null}`}

Endpoint auto-disable

If an endpoint fails every delivery for 5 consecutive days, it is automatically disabled to prevent wasting resources. You'll see it marked as Disabled in the endpoint list. Re-enable it manually and use Recover Failed to retry all missed messages.

{/* ── Endpoint Health Monitoring ─────────────────────────── */}

Endpoint health monitoring — dead endpoint alerts

Apps that push webhook events to this service have no way of knowing whether an endpoint is actually reachable. vibey monitors endpoint health automatically and alerts you when something is wrong.

How it works

All retries exhausted

When every retry attempt for a single message fails (7 attempts over ~27 hours by default), the message is marked as Failed and an alert appears in your dashboard. The sending app is never notified — you are.

Endpoint auto-disabled

If an endpoint fails every delivery for 5 consecutive days, it is automatically disabled. A critical alert appears in your dashboard. No further messages are delivered until you re-enable it.

What you see

When an alert fires, a red banner appears at the top of the Webhooks page showing the affected endpoint URL, alert type, and timestamp. You can expand the banner to see all active alerts, dismiss them individually, or dismiss all at once. Alerts are also logged and available via the API.

What the sending app should do

If your app pushes events to this service and needs to know whether endpoints are healthy, you can poll the health alerts API:

{`GET /api/webhooks/health-alerts
Authorization: Bearer 

# Response:
{
  "alerts": [
{
  "alert_type": "endpoint.disabled",
  "endpoint_url": "https://dead-server.example.com/webhook",
  "created_at": "2026-03-18T12:00:00Z",
  "acknowledged": false
}
  ],
  "unacknowledged": 1
}`}

After an alert

1. Check if the endpoint URL is still valid and reachable 2. Fix the issue on the receiving end (server down, DNS, firewall, etc.) 3. Re-enable the endpoint if it was auto-disabled 4. Use Recover Failed or Bulk Replay to retry all missed messages

{/* ── Signature Verification ─────────────────────────── */}

Signature verification — securing your webhooks

Every webhook delivery includes three headers that your clients should use to verify the message is authentic and hasn't been tampered with:

svix-id Unique message identifier (for deduplication) svix-timestamp Unix timestamp of when the message was sent svix-signature HMAC-SHA256 signature of the payload

The signing secret for each endpoint is shown on the endpoint detail page (click Show under Signing Secret). It starts with whsec_. Clients use this secret to verify signatures.

Verification in Node.js

{`import { Webhook } from "svix";

const wh = new Webhook("whsec_YOUR_SIGNING_SECRET");

// Express/Fastify handler
app.post("/webhook", (req, res) => {
  try {
const payload = wh.verify(req.body, {
  "svix-id": req.headers["svix-id"],
  "svix-timestamp": req.headers["svix-timestamp"],
  "svix-signature": req.headers["svix-signature"],
});
// payload is verified — process the event
console.log("Received:", payload.eventType, payload.payload);
res.status(200).json({ ok: true });
  } catch (err) {
res.status(400).json({ error: "Invalid signature" });
  }
});`}

Verification in Python

{`from svix.webhooks import Webhook

wh = Webhook("whsec_YOUR_SIGNING_SECRET")

# Flask / FastAPI handler
payload = wh.verify(request_body, {
"svix-id": headers["svix-id"],
"svix-timestamp": headers["svix-timestamp"],
"svix-signature": headers["svix-signature"],
})`}

Manual verification (any language)

{`# The signature is computed as:
# 1. Concatenate: "{svix-id}.{svix-timestamp}.{body}"
# 2. HMAC-SHA256 with the base64-decoded secret (strip "whsec_" prefix)
# 3. Base64-encode the result
# 4. Compare with the "v1,{signature}" value in svix-signature header

signature_input = svix_id + "." + svix_timestamp + "." + raw_body
expected = base64(hmac_sha256(base64_decode(secret), signature_input))
# svix-signature header contains: "v1,{expected}"`}

Svix provides official verification libraries for {' '}Node.js, Python, Go, Java, Ruby, Kotlin, C#, PHP, and Rust. {' '}Install via npm install svix, pip install svix, etc.

{/* ── Channels ─────────────────────────── */}

Channels — multi-tenant message routing

Channels let you route messages to specific endpoints without creating separate applications. This is ideal for multi-tenant setups where different clients should only receive their own events.

How channels work

Tag endpoints — Assign channel names to an endpoint (e.g. tenant_acme). Do this in the endpoint's Advanced tab or via the API.

Tag messages — When sending a message, include channels: ["tenant_acme"] in the body.

Selective delivery — Only endpoints with a matching channel receive the message. Endpoints with no channels receive all messages.

{`# Send a message to only "tenant_acme" endpoints
POST /app/${appUid}/msg/
{
  "eventType": "invoice.paid",
  "payload": {"invoiceId": "INV-001", "amount": 250},
  "channels": ["tenant_acme"]
}`}

{/* ── Custom Headers & Auth ─────────────────────────── */}

Custom headers & authentication per endpoint

Clients that validate inbound webhooks via an API key header or {' '}HTTP Basic Auth can be supported by setting custom outbound headers on each endpoint. Headers are configured per endpoint — each client gets their own credentials.

Set custom headers on an endpoint

{`PUT /app/${appUid}/endpoint/{ENDPOINT_ID}/headers/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "headers": {
"ApiKey": "client-security-token",
"Authorization": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
  }
}`}

Alternative — Basic Auth via URL

You can also embed Basic Auth credentials directly in the endpoint URL. The service will automatically send the Authorization: Basic ... header:

{`https://USERNAME:PASSWORD@their-server.com/webhook`}

Both ApiKey and Authorization headers can be set simultaneously — they are additive. All endpoints also receive the standard {' '}svix-id, svix-timestamp, and {' '}svix-signature HMAC headers for signature verification.

{/* ── Message Recovery ─────────────────────────── */}

Message recovery — retrying failed & missing messages

If messages fail or an endpoint was temporarily down, you have three recovery options available from the endpoint detail view's context menu (⋮):

{[ ['Recover Failed', 'Retries all messages that exhausted their retry schedule and were marked as Failed. Specify a start date — all failures since that date are re-queued.', `POST /app/${appUid}/endpoint/{ID}/recover/\n{"since": "2026-03-01T00:00:00Z"}`], ['Replay Missing', 'Re-delivers messages that were never attempted to this endpoint (e.g. the endpoint was added after messages were sent). Optionally filter by event type.', `POST /app/${appUid}/endpoint/{ID}/replay-missing/\n{"since": "2026-03-01T00:00:00Z"}`], ['Resend Single', 'Manually retry a specific message to a specific endpoint. Available from the message attempt detail or the endpoint\'s attempt list.', `POST /app/${appUid}/msg/{MSG_ID}/\nendpoint/{ENDPOINT_ID}/resend/`], ].map(([title, desc, api]) => (

{title}

{desc}

{api}

))}

All recovery operations are idempotent — running them multiple times won't cause duplicate deliveries (messages are deduplicated by svix-id).

{/* ── Rate Limiting ─────────────────────────── */}

Rate limiting — protecting your clients

Per-endpoint rate limiting caps the number of webhook deliveries per second. This prevents overwhelming a client's server during high-volume periods. Configure it in the endpoint's Advanced tab or via the API.

{`PATCH /app/${appUid}/endpoint/{ENDPOINT_ID}/
Authorization: Bearer ${token}
Content-Type: application/json

{"rateLimit": 100}     // 100 deliveries/second max
{"rateLimit": null}    // remove the limit`}

When the rate limit is hit, messages are queued and delivered as capacity becomes available — no messages are dropped.

{/* ── SOAP XML Example ─────────────────────────── */}

Example — SOAP XML payload delivery

For clients that consume SOAP XML instead of JSON, you can send a pre-formed XML payload through the webhook service. The service forwards it as-is with the correct content type — no conversion needed.

Push a SOAP XML event

{`POST /app/${appUid}/msg/
Authorization: Bearer ${token}
Content-Type: application/json

{
  "eventType": "document.signed",
  "payload": {
"rawXml": "\\n..."
  }
}`}

Your transformation service is responsible for converting internal domain events into the SOAP XML envelope before pushing. Two delivery strategies:

Option A — Forward as-is:{' '} Use a Svix Transformation on the endpoint to extract the raw XML and set Content-Type: text/xml.

Option B — JSON wrapper:{' '} Send the event as standard JSON containing the XML as a string field. The client parses the XML from the JSON body. Simpler to set up, no transformation needed.

{/* ── SDK Libraries ─────────────────────────── */}

SDK libraries & further resources

Svix provides official client libraries for both sending webhooks (from your app) and verifying them (in your clients' apps):

{[ ['JavaScript / TypeScript', 'npm install svix'], ['Python', 'pip install svix'], ['Go', 'go get github.com/svix/svix-webhooks/go'], ['Java / Kotlin', 'com.svix:svix (Maven)'], ['Ruby', 'gem install svix'], ['C# / .NET', 'dotnet add package Svix'], ['PHP', 'composer require svix/svix'], ['Rust', 'cargo add svix'], ].map(([lang, cmd]) => (

{lang} {cmd}

))}

Useful links

{[ ['Svix API Reference', 'https://api.svix.com/docs'], ['Webhook Verification Guide', 'https://docs.svix.com/receiving/verifying-payloads/how'], ['Svix Transformations', 'https://docs.svix.com/transformations'], ['GitHub — svix-webhooks', 'https://github.com/svix/svix-webhooks'], ].map(([label, url]) => ( {label} ↗ ))}