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

From the dashboard homepage, click on the "Settings" tab in the main navigation menu, and then select the "Webhooks" tab.

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

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