Webhooks
Webhooks allow you to receive real-time notifications when events happen in Ringyo AI. Instead of polling the API, events are pushed to your server automatically.How Webhooks Work
- You register a webhook endpoint URL
- Select which events you want to receive
- When an event occurs, Ringyo sends an HTTP POST to your URL
- Your server processes the event and responds with
200 OK
Setting Up Webhooks
Via Dashboard
- Go to Dashboard → Developers → Webhooks
- Click Add Endpoint
- Enter your webhook URL
- Select events to receive
- Save the signing secret
Via API
Available Events
Call Events
Appointment Events
Agent Events
Phone Number Events
Credit Events
Webhook Payload
All webhooks follow this structure:call.completed Example
appointment.created Example
Verifying Webhooks
Always verify webhook signatures to ensure they came from Ringyo AI.Signature Header
Each webhook includes a signature:Verification Example
Retry Logic
If your endpoint doesn’t respond with2xx:
- Ringyo retries up to 5 times
- Exponential backoff: 1s, 5s, 30s, 2m, 10m
- After 10 consecutive failures, webhook is auto-disabled
Best Practices
- Respond quickly — Return
200 OKwithin 5 seconds - Process async — Queue heavy processing for background
- Be idempotent — Handle duplicate deliveries gracefully
- Monitor health — Check webhook status in dashboard
Testing Webhooks
Send Test Event
From the Dashboard:- Go to Developers → Webhooks
- Click the webhook endpoint
- Click Send Test
Local Development
Use a tunneling service like ngrok:Troubleshooting
Webhook not receiving events
Webhook not receiving events
- Verify the endpoint URL is correct and publicly accessible
- Check that the webhook status is “active”
- Ensure you’ve subscribed to the correct events
- Check your server logs for errors
Invalid signature errors
Invalid signature errors
- Ensure you’re using the correct signing secret
- Verify you’re hashing the raw request body, not parsed JSON
- Check timestamp handling
Webhook disabled after failures
Webhook disabled after failures
- Fix the issue causing failures
- Re-enable the webhook in the dashboard
- Consider implementing health checks
Next Steps
- n8n Integration for webhook automation
- API Reference: Webhooks