Based on the available documentation, here are several troubleshooting steps for API integration issues with Retell AI:
Webhook Configuration Issues
If your webhooks have stopped working, verify the following:
Check Webhook URL Configuration: Ensure your webhook URL is correctly saved in Settings → Webhooks for account-level webhooks, or in the agent configuration for agent-level webhooks(1). A known issue involves webhook URLs not updating properly - the system may cache old webhook URLs even when new ones are displayed in the dashboard(2).
Verify Agent Version: If you’re using phone numbers with inbound webhooks, ensure the phone number is bound to the correct agent version that has the updated webhook URL(2). After changing the webhook URL, make sure to publish or update your agent configuration(2).
Response Requirements: Retell expects a successful status code (2xx) from your webhook endpoint(1). The webhook has a timeout of 10 seconds(1). If within 10 seconds no success status is received, the webhook will be retried, up to 3 times(1).
Check Detailed Logs: Review your Detail Logs for webhook failures. Common issues include 401 “Unauthorized” errors or timeout errors like “timeout of 10000ms exceeded”(3). If you see timeout errors, your server may not be responding within the 10-second window(3).
API Key Issues
Verify your API keys are valid and active. You can manage API keys in the “API Keys” section under System “Settings”(4). If a key is compromised, delete it immediately and create a new one(4).
Testing Steps
- Test with a new webhook URL to isolate configuration issues(3)
- Make a fresh test call after confirming settings are correct(2)
- Verify your endpoint is responding with a 200 status code within 10 seconds(3)
If the issue persists after verifying these settings, contact Retell support directly with your agent ID and call IDs for further investigation(2).