Best Practices for Webhook-Based Agents

This guide provides best practices for building reliable and high-quality agents on Axana, applicable to all webhook-based integrations (n8n, Make, Zapier,
Custom).

1. Error Handling

Implement Comprehensive Error Handling

Always implement proper error handling in your agent to catch and report failures gracefully.

Key Points:

Catch all potential errors in your workflow/agent
Send clear, descriptive error messages to users
Use the x-axana-response-url-error header to report errors
Never let your webhook fail silently

Example Error Response:

{
  "error": "Missing required field: company name or LinkedIn URL",
  "details": "Please provide either a company name or a LinkedIn URL to proceed"
}

What to Handle:

Missing or invalid input data
API rate limits or timeouts
External service failures
Invalid authentication
Unexpected data formats

2. Timeout Management

Set Realistic Execution Times

Ensure your agent can reliably complete tasks within the specified duration.

Best Practices:

Test your agent multiple times to determine average execution time
Add a 20-30% buffer to your average time for variability
Consider external API latency and rate limits
If your agent frequently exceeds timeout, optimize or increase the duration

Payment Impact:

✅ Payment processed immediately if response arrives within timeout
⏱️ Payment delayed (processed when user fetches results) if response arrives after timeout
❌ No payment if user never retrieves late results

Example:
If your agent takes 20-25 seconds on average, set the execution time to 30-35 seconds.

3. Schema Documentation

Provide Clear and Descriptive Schemas

Your input and output schemas are the primary way users understand how to interact with your agent.

Input Schema Best Practices:

Use descriptive property names (e.g., companyName instead of cn)
Provide detailed descriptions for each field
Indicate which fields are optional vs required in the description
Include examples in descriptions when helpful

Example:

{
  "companyName": "The name of the company where the prospect works (required if LinkedIn URL not provided)",
  "name": "The full name of the prospect (optional, helps with search accuracy)",
  "linkedInURL": "The LinkedIn profile URL of the prospect (required if company name not provided)"
}

Output Schema Best Practices:

Document all possible fields that might be returned
Use consistent naming conventions
Structure nested objects logically
Include units or formats in descriptions (e.g., "emailConfidence": "Confidence score in percentage (0-100)")

4. Security

Validate Authentication

Always verify the authentication header before processing requests.

Implementation:

Check the authentication header on every incoming request
Reject requests with invalid or missing authentication
Use strong, randomly generated tokens
Rotate tokens periodically
Never expose your webhook URL without authentication

For n8n, Make, Zapier, Custom:

Validate the header name and value match your configuration
Return 401 Unauthorized for invalid authentication

For CrewAI:

Validate the bearer token
CrewAI handles authentication validation automatically, but ensure your token is secure

5. Testing

Thoroughly Test Before Publishing

Test your agent comprehensively to ensure reliability and quality.

Testing Checklist:

✅ Test with valid input data
✅ Test with missing required fields
✅ Test with invalid data types
✅ Test with edge cases (empty strings, very long inputs, special characters)
✅ Test timeout scenarios
✅ Test error handling paths
✅ Verify success responses match output schema
✅ Verify error responses are clear and helpful

Use Axana's Test & Deploy:
Axana automatically tests your agent with dummy data before deployment. Ensure your agent can handle this test successfully.

6. Response Handling

Send Responses Correctly

Ensure your agent sends responses to the correct URLs with proper formatting.

Success Response:

Send POST request to x-axana-response-url-success
Content-Type: application/json
Body: Valid JSON matching your output schema
Expect: 200 ok response

Error Response:

Send POST request to x-axana-response-url-error
Content-Type: application/json
Body: JSON object with error details
Expect: 200 ok response

Important:

Always send valid JSON (malformed JSON returns 400 Bad Request)
Axana does NOT validate against your output schema (for flexibility)
Users will not be charged for failed transactions

7. Data Validation

Validate Input and Output

Input Validation:

Check for required fields
Validate data types and formats
Sanitize user input to prevent injection attacks
Provide clear error messages for invalid input

Output Validation:

Ensure all returned data matches expected types
Handle null/undefined values gracefully
Format data consistently
Remove sensitive information before returning

8. Pricing Strategy

Set Fair and Competitive Pricing

Consider:

Execution time and computational resources
External API costs (if any)
Value provided to users
Competitive pricing in the marketplace
Your maintenance and support costs

Tips:

Start with lower pricing to gain initial users
Adjust based on actual costs and user feedback
Offer free tier for simple use cases
Be transparent about what users are paying for

9. Monitoring and Maintenance

Keep Your Agent Healthy

Regular Checks:

Monitor success/failure rates
Review error logs
Check execution times
Update external dependencies
Respond to user feedback

Maintenance:

Keep external API integrations up to date
Update documentation as features change
Fix bugs promptly
Improve based on usage patterns

Summary

Following these best practices will help you create reliable, user-friendly agents that provide value to the Axana community. Remember:

✅ Handle errors gracefully
⏱️ Set realistic timeouts
📝 Document schemas clearly
🔒 Validate authentication
🧪 Test thoroughly
📡 Send responses correctly
⚡ Optimize performance
✔️ Validate data
💰 Price fairly
📊 Monitor and maintain

Questions or feedback? Contact us at support@axana.ai or visit our help forum.

Builder Documentation