Managing Webhooks

This document explains how to create, edit, delete, and test webhooks using the frontend UI. It focuses on actual frontend behavior and constraints observed in the code.

Accessing the Webhooks Page

1. Navigate to Dashboard → Webhooks
2. URL: /dashboard/webhooks
3. If no webhooks exist, an empty state with a “Create Your First Webhook” button is shown
4. Otherwise, a paginated list of webhook cards is displayed

Creating a Webhook

Creating a webhook is done via a multi-step modal wizard.

Step 1 — Basic Connection

Required fields:

• Webhook Name (title)
• Endpoint URL
  • Must be a valid absolute URL
• HTTP Method
  • Defaults to POST
• Authentication Type
  • None
  • Bearer Token
  • Basic Auth
  • API Key

Authentication-specific fields:

• Bearer
  • Token is required (validated before proceeding)
• Basic
  • Username and password fields shown
• API Key
  • Key name
  • Key value
  • Location (header or query parameter)

Click Next to proceed.
The modal validates required fields and blocks progression if validation fails.

Step 2 — Headers & Body Template

Fields:

• Headers
  • JSON string
  • Optional, but must be valid JSON if provided
• Body Template
  • JSON string
  • Required
  • May include mustache variables

On clicking Next:

• Headers and body template are JSON-parsed for validation
• Mustache variables are extracted from both fields
• Extracted variables are prepared for the Test step

Step 3 — Test Webhook

In this step:

• The UI displays all extracted mustache variables
• Users can provide test values (some defaults may be prefilled)
• Clicking Test:
  • Performs a real fetch() request from the browser
  • Replaces mustache variables with test values
  • Sends headers and body derived from the form
  • Displays response text and success/failure state

Important notes:

• Authentication settings are not automatically applied to the test request
• If auth is required, headers must explicitly include it
• Requests may fail due to browser CORS restrictions

Saving the Webhook

On final submit:

• Headers and body template strings are parsed into objects
• Payload is constructed and sent to the API
• On success:
  • The modal closes
  • The webhook list is refreshed

Editing a Webhook

1. Click the Edit icon on a webhook card
2. The UI fetches the webhook by ID
3. The modal opens pre-filled with existing values

Editable fields:

• Title
• URL
• Method
• Headers
• Body template
• Timeout
• Authentication settings

Behavior details:

• Headers and body template are stringified back into formatted JSON
• All visible fields are editable
• The webhook ID itself is not editable

On save:

• Data is sent to backend
• The list refreshes after success

⚠️ Important assumption
If the backend does not return sensitive auth values (e.g. tokens), the edit form will not display them.
Re-saving may overwrite or partially update auth data depending on backend behavior.

Deleting a Webhook

1. Click the Delete icon on a webhook card
2. A confirmation dialog appears:
   • Title: “Remove Webhook”
   • Message: “This action cannot be undone”
3. Confirming deletion:
   • Delete data from backend
   • Refreshes the list
4. Cancelling leaves the webhook untouched

Validation Rules (Frontend-Enforced)

• title: required, non-empty
• connection.url: required, must be a valid URL
• connection.body_template: required, must be valid JSON
• connection.headers: optional, but must be valid JSON if provided
• Bearer auth:
  • Token presence is explicitly checked before proceeding

Quirks & Edge Cases

• Browser-based testing
  • Subject to CORS
  • No proxy or fallback is implemented
• Auth not applied in tests
  • Auth config is saved but not injected into test requests
• Sequential pagination
  • Fetching all webhooks uses sequential requests, not parallel
• JSON-only body template
  • Body template must be valid JSON; arbitrary strings are not supported
• GET requests
  • Test requests omit the request body when method is GET

Summary

• Webhooks are managed via /dashboard/webhooks
• Create/edit uses a 3-step modal wizard
• Headers and body templates are JSON-based
• Testing runs directly from the browser
• Deletion requires explicit confirmation
• Some auth and CORS behaviors are non-obvious and should be understood before use