Webhook Testing and Configuration

This section provides comprehensive guidance on testing and configuring webhook integrations for Data Security. Learn how to prepare test payloads, run webhook tests, and troubleshoot common issues.

Overview of Webhook Testing

The Webhook Settings screen includes two buttons related to testing:

• Sample Payload Preview — Opens a window showing where the test payload file is stored on disk and explains how it can be edited.
• Test Webhooks — Sends the current version of the test payload to the configured webhook endpoint and displays the result in a detailed debug panel.

Purpose

This testing mechanism generates and sends schema-compliant payloads to help customers and integrators verify that:

• The webhook endpoint is reachable
• The expected schema is supported
• The system returns the correct status codes and responses

Preparing the Test Payload

The application uses a JSON file that contains the sample webhook payload.

Locating the Payload File

• File name: ztsuperna-test-payload.json
• Default location: Located in the application's configuration directory (for example, /opt/superna/sca/conf/ztsuperna-test-payload.json)

Finding the File Path

The exact file path is displayed in the application when you click the Sample Payload Preview button.

Editing the Payload

To modify the test payload:

1. Navigate to the file path

   Use the file path displayed in the Sample Payload Preview window.

2. Open the file with a text editor

   Use any Linux text editor to open the file:

   vi /opt/superna/sca/conf/ztsuperna-test-payload.json

   Or use another editor like nano:

   nano /opt/superna/sca/conf/ztsuperna-test-payload.json

3. Adjust the fields

   Modify the JSON fields to simulate the event you want to test. Ensure the payload follows the expected schema format.

4. Save the file

   Save your changes. No application restart is required.

Automatic Updates

The system always references this file when sending test requests, so any edits you make take effect immediately.

Running a Webhook Test

To send a test payload to your configured webhook endpoint:

1. Navigate to Webhooks

   Go to Integrations → Webhooks.

2. Click Test Webhooks

   Click the Test Webhooks button.

3. Review the results

   After the request completes, a debug panel will appear showing the test results.

The application will send the contents of ztsuperna-test-payload.json to your configured webhook URL.

Understanding the Debug Panel

The debug panel provides full visibility into the test transaction and displays:

Field	Description
Webhook URL	The target endpoint that received the payload
HTTP Status Code	Indicates whether the request succeeded (200 OK) or failed (4xx/5xx)
Success	Indicates if the operation succeeded or failed
Response Body	The text or JSON body returned by the endpoint
Timestamp	When the request was made
Duration	Time taken to complete the request
Payload View	A scrollable section showing the exact JSON that was sent

Error Highlighting

If the webhook request fails, the panel highlights the error in red for easy identification.

HTTPS and Certificate Handling

By default, webhook test requests ignore untrusted SSL certificates. This behavior ensures that test requests can still be performed in environments where internal or self-signed certificates are used.

Certificate Validation

This default behavior allows testing in development and staging environments without certificate warnings interrupting the workflow.

Troubleshooting

Common issues and their solutions:

Problem	Possible Cause	Recommended Action
No response or timeout	Webhook endpoint not reachable	Verify network access and endpoint URL
HTTP 400 or 500 errors	Invalid payload format or server error	Review the debug panel details and correct the payload fields
Payload not updated	File saved incorrectly or path mismatch	Confirm you edited the file shown in the modal window
SSL errors	Certificate validation conflicts	Check if ignoring untrusted certs is enabled by default

Troubleshooting Steps

1. Verify endpoint accessibility

   Ensure your webhook endpoint is reachable from the application server:

   curl -I https://your-webhook-endpoint.com/webhook

2. Check payload syntax

   Validate your JSON payload using a JSON validator or command-line tool:

   cat /opt/superna/sca/conf/ztsuperna-test-payload.json | jq .

3. Review debug panel details

   Examine the HTTP status code, response body, and error messages in the debug panel.

4. Test with a simple payload

   Start with a minimal payload to isolate configuration issues from data issues.

Important Notes

• The Sample Payload Preview button only displays the payload file location and editing instructions. It does not send any data to your endpoint.
• The Test Webhooks button is responsible for actually performing the request.
• All UI changes are visible on the Webhooks configuration page introduced in version 2.13.0.

See Also

• Webhook Integration Overview - Learn about webhook integration concepts
• Payload Structure Reference - Detailed webhook payload schema documentation
• Zero Trust API - API integration options