Skip to main content

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

  1. You register a webhook endpoint URL
  2. Select which events you want to receive
  3. When an event occurs, Ringyo sends an HTTP POST to your URL
  4. Your server processes the event and responds with 200 OK

Setting Up Webhooks

Via Dashboard

  1. Go to Dashboard → Developers → Webhooks
  2. Click Add Endpoint
  3. Enter your webhook URL
  4. Select events to receive
  5. Save the signing secret

Via API

Response includes a signing secret:

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 with 2xx:
  1. Ringyo retries up to 5 times
  2. Exponential backoff: 1s, 5s, 30s, 2m, 10m
  3. After 10 consecutive failures, webhook is auto-disabled

Best Practices

  1. Respond quickly — Return 200 OK within 5 seconds
  2. Process async — Queue heavy processing for background
  3. Be idempotent — Handle duplicate deliveries gracefully
  4. Monitor health — Check webhook status in dashboard

Testing Webhooks

Send Test Event

From the Dashboard:
  1. Go to Developers → Webhooks
  2. Click the webhook endpoint
  3. Click Send Test

Local Development

Use a tunneling service like ngrok:
Then use the ngrok URL as your webhook endpoint.

Troubleshooting

  • 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
  • Ensure you’re using the correct signing secret
  • Verify you’re hashing the raw request body, not parsed JSON
  • Check timestamp handling
  • Fix the issue causing failures
  • Re-enable the webhook in the dashboard
  • Consider implementing health checks

Next Steps