Webhook Components | Sylphx Documentation

WebhookManager

Full-featured interface for creating, editing, and deleting webhooks

WebhookDeliveryLog

View delivery attempts, statuses, and response details

Quick Start

All webhook components are available from the SDK. Wrap your app with SylphxProvider for automatic webhook context and API integration.

Installation

import {
  WebhookManager,
  WebhookDeliveryLog,
} from '@sylphx/platform-sdk/react'

WebhookManager

A complete interface for managing webhooks. Users can create new webhooks, edit existing ones, test delivery, and delete webhooks they no longer need. Perfect for settings pages and developer dashboards.

Create

Edit

Delete

Themeable

Basic Usage

import { WebhookManager } from '@sylphx/platform-sdk/react'

export default function SettingsPage() {
  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Webhook Settings</h1>
      <WebhookManager
        onWebhookCreated={(webhook) => {
          console.log('New webhook:', webhook)
          toast.success('Webhook created successfully')
        }}
        onWebhookUpdated={(webhook) => {
          console.log('Updated webhook:', webhook)
          toast.success('Webhook updated')
        }}
        onWebhookDeleted={(webhookId) => {
          console.log('Deleted webhook:', webhookId)
          toast.success('Webhook deleted')
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`webhooks`	`Webhook[]`	Array of webhooks (auto-fetched if not provided)
`availableEvents`	`string[]`	List of event types users can subscribe to
`onWebhookCreated`	`(webhook: Webhook) => void`	Callback when a new webhook is created
`onWebhookUpdated`	`(webhook: Webhook) => void`	Callback when a webhook is updated
`onWebhookDeleted`	`(webhookId: string) => void`	Callback when a webhook is deleted
`onWebhookTested`	`(webhookId: string, result: TestResult) => void`	Callback after testing a webhook
`onError`	`(error: Error) => void`	Callback on any operation error
`showTestButton`	`boolean`= true	Show button to test webhook delivery
`showSecretField`	`boolean`= true	Show secret field in create/edit form
`showDeliveryLogs`	`boolean`= false	Show recent delivery logs for each webhook
`allowMultiple`	`boolean`= true	Allow creating multiple webhooks
`maxWebhooks`	`number`	Maximum number of webhooks allowed
`defaultEvents`	`string[]`	Pre-selected events for new webhooks
`requiredEvents`	`string[]`	Events that must be selected
`disabledEvents`	`string[]`	Events that cannot be selected
`validateUrl`	`(url: string) => boolean \| string`	Custom URL validation function
`emptyState`	`ReactNode`	Custom empty state when no webhooks exist
`variant`	`"default" \| "compact" \| "card"`= "default"	Visual style variant
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Webhook Object

Property	Type	Description
`id`required	`string`	Unique webhook identifier
`url`required	`string`	Endpoint URL for webhook delivery
`events`required	`string[]`	Array of subscribed event types
`secret`	`string`	HMAC signing secret
`enabled`	`boolean`= true	Whether the webhook is active
`description`	`string`	Optional description
`createdAt`required	`Date`	When the webhook was created
`updatedAt`	`Date`	When the webhook was last updated
`lastDelivery`	`DeliveryStatus`	Status of the most recent delivery
`metadata`	`Record<string, unknown>`	Custom metadata

Advanced Examples

<WebhookManager
  availableEvents={[
    'user.created',
    'user.updated',
    'user.deleted',
    'payment.succeeded',
    'payment.failed',
    'subscription.created',
    'subscription.cancelled',
  ]}
  defaultEvents={['user.created', 'payment.succeeded']}
  requiredEvents={['user.created']}
  disabledEvents={['user.deleted']} // Premium only
  onWebhookCreated={(webhook) => {
    analytics.track('webhook_created', {
      events: webhook.events,
    })
  }}
/>

Webhook Secrets

When showSecretField is enabled, users can set their own signing secret. Otherwise, secrets are automatically generated and managed by the platform.

WebhookDeliveryLog

Display delivery attempts with status indicators, timestamps, response codes, and detailed request/response information. Essential for debugging webhook issues and monitoring delivery health.

Success

Failed

Pending

Retry

Basic Usage

import { WebhookDeliveryLog } from '@sylphx/platform-sdk/react'

export default function WebhookDetailsPage({ params }) {
  return (
    <div className="max-w-4xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Delivery History</h1>
      <WebhookDeliveryLog
        webhookId={params.webhookId}
        onRetry={(deliveryId) => {
          console.log('Retrying delivery:', deliveryId)
          toast.info('Retrying webhook delivery...')
        }}
        onDeliveryClick={(delivery) => {
          // Show detailed modal
          setSelectedDelivery(delivery)
          setModalOpen(true)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`webhookId`required	`string`	Webhook ID to fetch deliveries for
`deliveries`	`Delivery[]`	Array of deliveries (auto-fetched if not provided)
`onDeliveryClick`	`(delivery: Delivery) => void`	Callback when a delivery row is clicked
`onRetry`	`(deliveryId: string) => void`	Callback when retry button is clicked
`onRetryAll`	`() => void`	Callback when "Retry All Failed" is clicked
`showRetryButton`	`boolean`= true	Show retry button for failed deliveries
`showRetryAllButton`	`boolean`= true	Show "Retry All Failed" button
`showRequestDetails`	`boolean`= true	Show expandable request/response details
`showFilters`	`boolean`= true	Show status filter tabs
`showSearch`	`boolean`= false	Show event type search
`showTimestamps`	`boolean`= true	Show relative timestamps
`showStatusCode`	`boolean`= true	Show HTTP response status code
`showDuration`	`boolean`= true	Show request duration
`showEventType`	`boolean`= true	Show event type column
`filterByStatus`	`"all" \| "success" \| "failed" \| "pending"`	Pre-filter by status
`filterByEvent`	`string`	Pre-filter by event type
`pageSize`	`number`= 25	Number of deliveries per page
`infiniteScroll`	`boolean`= true	Enable infinite scroll loading
`pollInterval`	`number`= 0	Interval to poll for new deliveries (ms)
`emptyState`	`ReactNode`	Custom empty state content
`loadingState`	`ReactNode`	Custom loading state
`variant`	`"default" \| "compact" \| "detailed"`= "default"	Visual density variant
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Delivery Object

Property	Type	Description
`id`required	`string`	Unique delivery identifier
`webhookId`required	`string`	Associated webhook ID
`eventId`required	`string`	Event that triggered this delivery
`eventType`required	`string`	Type of event (e.g., user.created)
`status`required	`"success" \| "failed" \| "pending"`	Delivery status
`statusCode`	`number`	HTTP response status code
`duration`	`number`	Request duration in milliseconds
`attempt`required	`number`	Attempt number (1-5)
`maxAttempts`	`number`= 5	Maximum retry attempts
`nextRetryAt`	`Date`	When the next retry will occur
`error`	`string`	Error message if failed
`requestHeaders`	`Record<string, string>`	Request headers sent
`requestBody`	`string`	Request payload (JSON)
`responseHeaders`	`Record<string, string>`	Response headers received
`responseBody`	`string`	Response body received
`createdAt`required	`Date`	When the delivery was attempted

Advanced Examples

<WebhookDeliveryLog
  webhookId={webhookId}
  showFilters={true}
  showSearch={true}
  showRetryAllButton={true}
  filterByStatus="failed"
  onRetryAll={async () => {
    await retryAllFailed(webhookId)
    toast.success('Retrying all failed deliveries')
  }}
  onRetry={async (deliveryId) => {
    await retryDelivery(deliveryId)
    toast.info('Retry scheduled')
  }}
/>

Large Payloads

Request and response bodies are truncated after 10KB in the UI. Use the onDeliveryClick callback to fetch and display full payloads in a modal.

Theming

All webhook components support theming via the theme prop. Customize colors, fonts, and spacing to match your brand.

Custom Theme

import { WebhookManager, WebhookDeliveryLog, defaultTheme, type ThemeVariables } from '@sylphx/platform-sdk/react'

const customTheme: ThemeVariables = {
  ...defaultTheme,
  colorPrimary: '#8b5cf6',
  colorPrimaryHover: '#7c3aed',
  colorBackground: '#ffffff',
  colorForeground: '#1f2937',
  colorMuted: '#f3f4f6',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  colorSuccess: '#10b981',
  colorError: '#ef4444',
  colorWarning: '#f59e0b',
  fontFamily: 'Inter, sans-serif',
  fontSize: '14px',
  borderRadius: '0.75rem',
}

<WebhookManager theme={customTheme} />
<WebhookDeliveryLog webhookId={id} theme={customTheme} />

Property	Type	Description
`colorPrimary`	`string`= #000000	Primary brand color
`colorPrimaryHover`	`string`= #1f2937	Primary color on hover
`colorBackground`	`string`= #ffffff	Component background
`colorForeground`	`string`= #1f2937	Primary text color
`colorMuted`	`string`= #f3f4f6	Muted background
`colorMutedForeground`	`string`= #6b7280	Secondary text color
`colorBorder`	`string`= #e5e7eb	Border color
`colorSuccess`	`string`= #10b981	Success status color
`colorError`	`string`= #ef4444	Error/failed status color
`colorWarning`	`string`= #f59e0b	Warning/pending status color
`fontFamily`	`string`= system-ui	Font family
`borderRadius`	`string`= 0.5rem	Border radius

Best Practices

Require HTTPS

Use URL validation to enforce HTTPS endpoints. Never allow HTTP webhooks in production.

Show Delivery Status

Display recent delivery status in the webhook list so users can quickly identify issues.

Enable Retry

Allow users to manually retry failed deliveries. Sometimes temporary issues cause failures.

Provide Test Functionality

Let users test their webhook endpoints before relying on them for production events.

Need more customization?

Use the useWebhooks hook for fully custom UI while keeping all the functionality.

Webhooks Overview Background Jobs

Webhooks

Learn about webhook events and security

Background Jobs

Process webhooks asynchronously