Webhooks - Vextro Docs

Vextro includes a webhook management interface with two pages: a list view showing all configured webhooks, and a detail page for creating, editing, and monitoring individual webhooks.

Setup

Import and mount both page components in your Astro routing:

---
// List page — e.g., /admin/webhooks
import VextroWebhooksPage from "vextro/pages/VextroWebhooksPage.astro";

// Detail page — e.g., /admin/webhooks/[webhookId]
import VextroWebhookDetailPage from "vextro/pages/VextroWebhookDetailPage.astro";
---

<!-- List view -->
<VextroWebhooksPage
  convex={convex}
  api={api}
  basePath="/admin"
  config={config}
/>

<!-- Detail/create view -->
<VextroWebhookDetailPage
  convex={convex}
  api={api}
  basePath="/admin"
  config={config}
  webhookId={webhookId}
/>

Page props

Both pages share these common props:

Prop	Type	Required	Description
`convex`	`ConvexClient`	Yes	Convex client instance.
`api`	`AdminAPI`	Yes	Admin API reference from `createVextroAdminModule`.
`brandName`	`string`	No	Custom brand name displayed in the header. Defaults to `"Vextro"`.
`basePath`	`string`	No	URL base path for routing links.
`config`	`VextroConfig`	No	Vextro configuration object.

The detail page also accepts:

Prop	Type	Required	Description
`webhookId`	`string`	Yes	The webhook ID to edit, or `"new"` to create a new webhook.

List view

The webhooks list page displays a table of all configured webhooks with:

Name and URL (truncated for readability)
Events shown as color-coded badges
Status indicator (active/disabled)
Last updated timestamp

Click any row to navigate to its detail page. Use the "New Webhook" button to create a new webhook.

Event badges

Event	Color
`document.create`	Emerald
`document.update`	Blue
`document.delete`	Red
`document.publish`	Violet
`ping`	Gray

Detail view

The detail page supports both creating new webhooks and editing existing ones.

Configuration

Field	Description
Name	Human-readable webhook name.
URL	The endpoint URL that receives POST requests.
Secret	Optional shared secret for HMAC-SHA256 signature verification.
Events	Select which document events trigger this webhook.
Collections	Optionally limit the webhook to specific collections.
Enabled	Toggle the webhook on or off.

Retry configuration

Configure exponential backoff for failed deliveries:

Setting	Default	Range	Description
Max Retries	`3`	0--10	Maximum number of retry attempts.
Initial Delay	`5000` ms	1000+	Delay before the first retry.
Backoff Multiplier	`2`	1--10	Multiplier applied to each successive retry delay.

A live preview shows the calculated retry delays based on your settings.

Delivery history

For existing webhooks, the detail page shows a chronological delivery log with:

Event type and status (delivered, failed, pending, retrying)
HTTP status code and attempt count
Expandable details showing error messages, response bodies, and per-attempt logs

Actions

Action	Description
Save / Create	Persist the webhook configuration.
Test Ping	Send a test ping event to verify connectivity (existing webhooks only).
Delete	Remove the webhook permanently (existing webhooks only).
Replay	Retry a failed delivery (per-delivery action).

Webhook actions use the current authenticated admin session. Successful creates and deletes return to the webhook list; successful edits and delivery actions refresh the current detail view.