--- page_source: https://juspay.io/sea/docs/dashboard-sea/docs/payments/webhook-configuration page_title: Webhook Configuration --- # Webhook Settings: A Comprehensive Guide ## Overview The Webhook Settings module provides comprehensive configuration and management capabilities for webhook endpoints and event notifications within the Juspay payment platform. It enables real-time notification delivery to merchant systems when payment events occur, ensuring seamless integration and automated business process triggers. This module offers configuration and management tools for setting up intelligent webhook routing that determines how payment event notifications are delivered to your systems based on various business criteria and integration requirements. ## Accessing the Module To access the Webhook Settings page, navigate to the following URL: [https://portal.juspay.in/settings/webhooks](https://portal.juspay.in/settings/webhooks) From the dashboard homepage, click on the "Settings" tab in the main navigation menu, and then select the "Webhooks" tab. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Webhooks%20Settings%201.png) *Webhooks Settings* ## Prerequisites and Permissions Before configuring Webhook Settings, ensure you have the appropriate access: ### Required Permissions **Basic Access** : `settings_webhook` ACL permission is required to access the Webhook Settings module **Configuration Rights** : Same `settings_webhook` permission with ReadWrite access allows creation and modification of webhook configurations **Custom Headers Management** : ReadWrite access to `settings_webhook` enables custom header creation, editing, and deletion ## Key Components of Webhook Configuration * **Primary Webhook Configuration** – Set up your main webhook endpoint with secure authentication and advanced delivery options. * **Secondary Webhook Management** – Configure backup endpoints, route events, and balance traffic across multiple webhook URLs. * **Custom Headers Management** – Add authentication, tracking, integration, and security headers for flexible webhook delivery. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Webhooks%20Settings%202-gJ2Ne.png) *Webhooks Custom Headers* * **Event Subscription Management** – Easily enable, disable, and route webhook events to their respective URLs with full validation. ![Image](https://dth95m2xtyv8v.cloudfront.net/tesseract/assets/dashboard/Webhooks%20Settings%203.png) *Webhook Events* ## Step-by-Step Configuration Instructions ### Configuring Primary Webhook Settings #### Step 1: Primary Webhook URL Setup **Access Primary Configuration** * Navigate to the Webhook Settings section within the webhooks tab * Locate the "Primary WebHook URL" field for main endpoint configuration **Configure Webhook URL** * Enter your webhook endpoint URL in the text input field * Ensure the URL uses HTTPS protocol (required for security) * Validate that the URL format is correct and accessible from Juspay servers * The URL will receive immediate notifications after an event is triggered, such as payment success or refund. #### Step 2: Authentication Configuration **Username Setup** * Locate the "Username" field for HTTP Basic Authentication * Enter the username that matches your webhook endpoint's authentication requirements * This serves as the identifier for secure webhook delivery **Password Setup** * Locate the "Password" field for HTTP Basic Authentication * Enter a secure password that matches your webhook endpoint's requirements * The password is masked for security and stored securely #### Step 3: Advanced Configuration Options **Gateway Response Configuration** * Locate the "Add Full Gateway Response" toggle switch * Enable this option to include complete payment gateway responses in webhook payloads * Consider the impact on payload size when enabling this feature **Webhook Encryption Configuration** (when available) * Locate the "Webhook Encryption Key" dropdown if the feature is enabled * Select from available JWT keys or choose "NO" for no encryption * Only enable encryption if your system has proper decryption logic in place ### Managing Secondary Webhook URLs #### Step 1: Understanding Secondary Webhooks Secondary webhook URLs serve multiple purposes: * **Redundancy** : Backup endpoints when primary endpoints are unavailable * **Event Routing** : Route specific events to specialized systems * **Load Distribution** : Distribute webhook traffic across multiple endpoints * **System Separation** : Send different event types to different systems #### Step 2: Adding Secondary URLs **Create New Secondary URL** * Navigate to the "Secondary WebHook URL" section * Click the "+Configure Secondary Webhook URL" button * Enter the secondary webhook URL in the modal form * Validate that the URL is unique and properly formatted * Click "Configure" to add the secondary URL **Validation Requirements** * URL cannot be empty * Must be a valid HTTPS URL * Cannot duplicate existing secondary URLs * Cannot match the primary webhook URL #### Step 3: Managing Existing Secondary URLs **Editing Secondary URLs** * Locate the secondary URL in the visual list * Click on the URL chip/tag to open the edit modal * Modify the URL in the input field * Click "Configure" to save changes **Deleting Secondary URLs** * Open the edit modal for the secondary URL * Click the trash icon in the modal footer * Confirm the deletion when prompted ### Custom Headers Configuration #### Step 1: Understanding Custom Headers Custom headers enable various integration scenarios: * **Custom Authentication** : API keys or tokens for endpoint authentication * **Request Tracking** : Correlation IDs or tracking headers for monitoring * **System Integration** : Headers required by receiving systems or middleware * **Debugging** : Diagnostic headers for troubleshooting #### Step 2: Creating Custom Headers **Add New Header** * Navigate to the "Webhooks Custom Headers" section * Click the "Create Webhook Header" button * Enter the header name in the "Name" field * Enter the header value in the "Value" field * Validate that the header name is unique and doesn't contain invalid characters * Click "Add Webhook" to create the header **Validation Rules** * Header names must be unique across all custom headers * Header names cannot contain the '#' character #### Step 3: Managing Existing Headers **Viewing Headers** * Custom headers are displayed in a comprehensive data table * Sortable columns allow organization by name or value * Pagination controls help navigate through multiple headers * Search functionality enables quick header location **Editing Headers** * Locate the header in the table * Click the edit icon in the actions column * Enter the new value in the update modal * Click "Submit" to save changes * Confirm the update in the confirmation popup **Deleting Headers** * Locate the header in the table * Click the delete icon in the actions column * Confirm deletion in the popup dialog * Verify the header is removed from the table ### Webhook Events Configuration #### Step 1: Understanding Event Categories Webhook events are organized into logical categories: **Order Events** : Notifications related to order lifecycle and status changes **Refund Events** : Notifications for refund processing and status updates **Transaction Events** : Notifications for individual transaction processing **Chargeback Events** : Notifications for chargeback and dispute processing **Customer Events** : Notifications related to customer account changes **Notification Events** : System-level notifications and alerts **Mandate Events** : Notifications for recurring payment mandate management **Tokenization Events** : Notifications for payment method tokenization **Auto Refund Events** : Notifications for automated refund processing #### Step 2: Configuring Event Subscriptions **Access Event Configuration** * Navigate to the "Webhook Events" section * Review the event category list on the left side * Select an event category to view available events * Configure individual events within the selected category #### Step 3: Individual Event Configuration **Enable/Disable Events** * Select an event category from the left panel * Review the list of available events in the right panel * Check the checkbox next to each event you want to enable * Uncheck events you want to disable * Configure secondary URL routing if secondary URLs are available **Secondary URL Routing for Events** When secondary webhook URLs are configured: * Enable the desired event using the checkbox * Select a secondary URL from the dropdown if available * Choose "Primary" to route to the main webhook URL * Choose a specific secondary URL to route to that endpoint #### Step 4: Event Configuration Validation **Validation Rules** * At least one event must be enabled for webhook functionality * Secondary URLs must have at least one assigned event if they exist * Events must be properly routed to available endpoints **Validation Messages** * Real-time validation occurs as you configure events * "Secondary URL must have one webhook event" appears when secondary URLs have no assigned events * Invalid configurations prevent form submission ## Managing Existing Webhook Configurations ### Viewing Current Configuration **Configuration Overview** * Review current webhook settings in the main dashboard * Check active event subscriptions and their routing * Monitor secondary URL configurations and assignments * Verify custom header settings and values ### Modifying Webhook Settings **Configuration Updates** * Webhook configurations can be directly modified through the interface * Changes take effect immediately upon successful submission * All modifications require appropriate permissions * Configuration history is maintained for audit purposes **Testing and Validation** * Use webhook testing tools to verify endpoint accessibility * Test authentication credentials with your receiving systems * Validate event routing and secondary URL functionality * Monitor webhook delivery success rates after configuration changes ## Use Cases ### Use Case 1: E-commerce Order Processing Integration **Scenario** : E-commerce merchant needs real-time order status updates for inventory and customer service systems. **Expected Behavior** : * Real-time notifications for all order status changes * Automatic failover to secondary URL if primary endpoint fails * Secure delivery with authentication credentials * Custom headers enable proper request routing in merchant systems **Outcome** : Real-time order processing with efficiency. ### Use Case 2: Subscription Business Recurring Payment Monitoring **Scenario** : Subscription service needs to monitor recurring payments and mandate management for customer retention. **Expected Behavior** : * Automated subscription lifecycle management * Secure data transmission with encryption * Event-specific routing for different business processes * Reliable delivery with backup endpoint configuration **Outcome** : Automated subscription lifecycle management with secure data transmission. ## Troubleshooting ### Configuration Validation Errors **"Should be a https url"** * **Cause** : URL doesn't use HTTPS protocol * **Resolution** : Ensure all webhook URLs start with https:// **"Webhook URL cannot be empty"** * **Cause** : Empty URL field in webhook configuration * **Resolution** : Enter a valid HTTPS URL **"Invalid Url"** * **Cause** : URL format is incorrect * **Resolution** : Verify URL format and ensure it's properly structured **"Primary URL cannot be same as Secondary URL"** * **Cause** : Primary and secondary URLs are identical * **Resolution** : Use different URLs for primary and secondary endpoints ### Custom Headers Validation Errors **"This key is already created. Please type a different key."** * **Cause** : Header name already exists * **Resolution** : Use a unique header name **"Key cannot contain '#' character"** * **Cause** : Header name contains invalid character * **Resolution** : Remove the '#' character from header name ### Event Configuration Errors **"Secondary URL must have one webhook event"** * **Cause** : Secondary URL has no assigned events * **Resolution** : Assign at least one webhook event to the secondary URL **"No values are changed"** * **Cause** : No modifications detected in form * **Resolution** : Make at least one change before saving ### Permission and Access Errors **"You do not have access"** * **Cause** : User lacks required permissions for the operation * **Resolution** : Contact administrator to assign `settings_webhook` permissions **"Something went wrong. Please try again"** * **Cause** : General system error during API operations * **Resolution** : Retry the operation; contact support if issue persists