Webhooks - FAQ
Find answers to common questions about Clearout webhooks.
General Questions
What are webhooks and why should I use them?
Webhooks are HTTP callbacks that automatically notify your application when events occur in Clearout. They provide several benefits:
- Real-time notifications instead of polling for updates
- Reduced server load and improved efficiency
- Automatic handling of timeout scenarios
- Better integration with your existing systems
How many webhooks can I configure?
You can configure up to 2 webhook endpoints in your Clearout account. This allows you to:
Multiple Endpoints
Send notifications to different systems like your backend API and CRM system.
Backup Redundancy
Set up a primary and backup endpoint for improved reliability.
What happens if my webhook endpoint is down?
Clearout automatically retries failed webhook deliveries with an exponential backoff strategy:
- Retries follow a 5-minute exponential backoff pattern
- After all retries are exhausted, the webhook is marked as permanently failed
How do I access webhook settings in the dashboard?
To access webhook settings:
- Log in to your Clearout App
- Click on Developer in the main navigation
- Select Webhook from the developer submenu
- You'll see the "My Webhooks" section with options to create and manage webhooks
What do the different action buttons in the webhook table do?
The webhook table has four action buttons:
- Eye icon (View Event Logs) - Shows detailed delivery history and JSON payloads
- Paper plane icon (Test Events) - Sends test payloads to verify your endpoint
- Pencil icon (Edit) - Modifies webhook configuration
- Trash icon (Delete) - Removes the webhook permanently
Technical Questions
How do I verify that webhooks are coming from Clearout?
Clearout uses HMAC-SHA256 signature verification to ensure webhook authenticity:
Signature Header
Check the x-co-webhook-signature header for signature verification.
Timestamp Validation
Verify timestamps to prevent replay attacks (recommended: 5 minutes max age).
Secret Key
Use your webhook secret key to generate and verify HMAC signatures.
Implementation
See our Validate Deliveries guide for code examples.
Can I test webhooks locally during development?
Yes! You can test webhooks locally using several methods:
ngrok (Recommended)
Use ngrok to create a secure tunnel to your local development server.
Dashboard Testing
Use the built-in test feature in your Clearout App to send sample payloads.
Note: All webhook endpoints must use HTTPS. Test events are sent immediately and appear in your event logs.
What HTTP status codes should my webhook endpoint return?
Your webhook endpoint should return appropriate HTTP status codes:
- 200 OK: Webhook processed successfully
- 4xx/5xx: Will trigger retry attempts
- Response time: Keep responses under 30 seconds
- Idempotency: Handle duplicate webhook deliveries gracefully
Billing Questions
Are webhook events charged?
Webhook events are charged conditionally, meaning that events that are triggered by service actions will be charged if they have not already been charged as part of the service action request.
- Timeout scenarios: If a service times out but webhooks are enabled, you're charged for the service, not the webhook delivery
- Bulk events: Not charged (free notifications)
- Test events: Always free
Refer to Webhook Events to know chargeable and non-chargeable events.
Do I get charged for failed webhook deliveries?
No, you are only charged for the original service action, not for webhook delivery attempts:
- Charging occurs when the service completes, not when webhooks are delivered
- Retry attempts are free and don't incur additional charges
- Failed webhook deliveries don't affect your billing
Troubleshooting
My webhook endpoint is not receiving events. What should I check?
If you're not receiving webhook events, check these common issues:
HTTPS Requirement
Ensure your endpoint uses HTTPS (HTTP is not supported).
Firewall/Security
Check if your firewall is blocking incoming requests from Clearout.
Event Selection
Verify that you've selected the correct events in your webhook configuration.
Event Logs
Check your webhook event logs in the dashboard for delivery status.
How can I monitor webhook delivery success rates?
You can monitor webhook delivery through several methods:
- Dashboard Logs: View delivery status and response codes in your webhook event logs
- Response Monitoring: Implement logging in your webhook endpoint to track received events
- Health Checks: Set up monitoring for your webhook endpoint availability
- Alerting: Configure alerts for failed webhook deliveries