Testing Your SolidATS Webhook Integration

Testing Your SolidATS Webhook Integration

This guide provides a comprehensive approach to testing your app’s webhook integration with the SolidATS platform.

Understanding the Testing Process

SolidATS provides built-in testing tools that allow you to verify your webhook implementation without affecting real candidate data. The testing process involves:

1. Sending test webhook payloads to your app’s API endpoint
2. Validating the responses your app sends back
3. Inspecting detailed logs of request/response cycles

Prerequisites for Testing

Before testing, ensure you have:

• Configured your app with a valid entry URL in the SolidATS dashboard
• Implemented an endpoint that can receive webhook payloads
• Set up any necessary authorization if using the auth_header_secret feature

Manual Testing Using the Test Button

The quickest way to test your implementation is using the built-in Test Button in the App Edit page:

1. Navigate to Apps → Your App → Edit
2. Configure your app’s entry URL and other settings
3. Scroll down to the Webhook Testing section
4. Click the “Test Webhook” button

This will:

• Generate a realistic test payload with randomized candidate data
• Send a POST request to your configured entry URL
• Show real-time results of the test
• Validate your app’s response format
• Store the test results in the webhook logs

Understanding Test Results

The test output provides immediate feedback on your implementation:

• Success: Your webhook responded correctly with valid data
• Format Error: Your response is missing required fields or has incorrect formatting
• Connection Error: SolidATS couldn’t connect to your endpoint

Common validation errors include:

• Missing required fields (candidate_id, pipeline_step_id, call_secret, rating)
• Values in response not matching the original request values
• Rating value outside the allowed 0-100 range
• Malformed JSON response

Webhook Logs Analysis

For deeper investigation:

1. Click “View Logs” in the Webhook Testing section
2. Find your test in the logs list
3. Click “View Details” to see:
   • Complete request payload sent to your app
   • Complete response received from your app
   • Timestamps and status information
   • Any validation errors or connection issues

This helps debug issues by comparing expected vs. actual data formats.

Testing Synchronous vs. Asynchronous Implementations

Synchronous Testing (Immediate Response)

If your app is configured with “Immediately returns result” enabled:

• Your endpoint must return a valid response immediately
• The test results will show instantly
• Response validation happens in real-time

Asynchronous Testing (Callback Response)

If your app is configured with “Immediately returns result” disabled:

1. Your endpoint should return a 200 OK acknowledgment
2. Process the request asynchronously
3. Send results later by making a POST request to: https://[your-solidats-domain]/webhooks/app-callback
4. Include the same candidate_id, pipeline_step_id, and call_secret in your callback

The test will show “Waiting for callback…” until your app sends the response to the callback URL.

Setting Up a Local Development Environment

For local development:

1. Use a tool like ngrok (https://ngrok.com/) to expose your local server:

   ngrok http 8000

2. Set your app’s entry URL to the ngrok URL (e.g., https://a1b2c3d4.ngrok.io/webhook)

3. Implement your webhook handler to:

   • Parse the incoming JSON payload
   • Extract and store the candidate_id, pipeline_step_id, and call_secret
   • Generate a response with the same values
   • Add your assessment logic and rating

Creating an Automated Testing Suite

For continuous integration:

1. Create test cases that simulate both valid and invalid responses

2. Test synchronous and asynchronous flows:

   // Example test case structure
   {
     "type": "sync", // or "async"
     "payload": { /* Sample payload */ },
     "expectedResponse": { /* Expected format */ },
     "shouldSucceed": true // or false
   }

3. Verify edge cases:

   • Missing fields
   • Invalid rating values
   • Malformed JSON
   • Timeouts
   • Network errors

Response Format Testing

Ensure your app can handle and respond with the correct format. Test all supported response formats:

1. Standard JSON object:

   {
     "candidate_id": "test_abc123",
     "pipeline_step_id": "step_12345",
     "call_secret": "secret_token_xyz",
     "rating": 85
   }

2. Array format (first item is used):

   [
     {
       "candidate_id": "test_abc123",
       "pipeline_step_id": "step_12345",
       "call_secret": "secret_token_xyz",
       "rating": 85
     }
   ]

3. Nested under “output” key:

   {
     "output": {
       "candidate_id": "test_abc123",
       "pipeline_step_id": "step_12345",
       "call_secret": "secret_token_xyz",
       "rating": 85
     }
   }

Troubleshooting Common Issues

Connection Timeouts

• Ensure your server responds within 30 seconds
• For longer processing, use the asynchronous mode

Authentication Failures

• Verify your auth_header_secret is correctly configured
• Check that your endpoint properly validates the Authorization header

Missing Field Errors

• Ensure all required fields are included
• Double-check field names (case-sensitive)
• Validate that ID fields match exactly with those received

Invalid Rating Errors

• Ensure rating is a number between 0-100
• Check for string vs. number type issues

Best Practices for Testing

1. Start with manual tests using the Test Button
2. Review webhook logs to debug specific issues
3. Implement automated tests for regression testing
4. Test both synchronous and asynchronous modes
5. Verify handling of various response formats
6. Test error scenarios and recovery processes
7. Document any specific requirements for your app

By following these testing procedures, you can ensure your webhook integration works correctly and consistently with the SolidATS platform.