Webhook Failures, API Errors, and CRM Sync Issues
Fix webhook delivery failures, resolve API 401/403 errors, troubleshoot CRM sync issues, and test your integrations with Teammates.ai.
Common Integration Issues at a Glance
The table below covers the most frequent integration problems, their likely causes, and the fastest fix for each.
| Symptom | Likely Cause | Quick Fix |
|---|---|---|
| Webhook not firing | URL unreachable or wrong event type selected | Verify URL is public and event type matches |
| Webhook returns 401/403 | Signature verification failing | Update webhook secret on both sides |
| API calls return 401 Unauthorized | Expired or missing API token | Regenerate token in Dashboard > Settings > API |
| API calls return 403 Forbidden | Token lacks required permissions | Check token permissions and user role |
| CRM data not syncing | Field mapping mismatch or expired OAuth | Re-authorize CRM and review field mappings |
Webhook Not Firing
When your webhook endpoint does not receive events from Teammates.ai, the issue is usually URL reachability, event configuration, or authentication.
- 1
Verify the webhook URL is publicly reachable
Your webhook URL must be a public HTTPS endpoint. Localhost URLs, internal IPs, and HTTP (non-HTTPS) URLs will not work. Test reachability by sending a curl request to the URL from an external machine.
- 2
Confirm the correct event types are selected
Go to Dashboard > Settings > Webhooks and check which event types are enabled for your webhook. If you only selected "conversation.closed" but expect "conversation.created" events, you will not receive them.
- 3
Check webhook logs for HTTP status codes
In the webhook settings, review the delivery log. Each attempt shows the HTTP status code returned by your endpoint. A 200 means success. A 4xx or 5xx means your server rejected or failed to process the request.
- 4
Use the "Send Test Webhook" feature
Click "Send Test" in your webhook settings. Teammates.ai sends a sample event to your endpoint. Check your server logs to confirm receipt and correct processing.
- 5
Verify signature verification
If your server validates webhook signatures, confirm the signing secret in your code matches the one in Dashboard > Settings > Webhooks. A mismatch causes your server to reject valid events with a 401 or 403.
API 401/403 Errors
If your API calls to Teammates.ai return 401 (Unauthorized) or 403 (Forbidden), the problem is with your API token, permissions, or rate limits.
- 1
Regenerate your API token
Go to Dashboard > Settings > API and generate a new token. Replace the old token in your application code. Tokens can expire or be revoked, so always use the latest one.
- 2
Verify the Authorization header format
The API expects: Authorization: Bearer YOUR_TOKEN. Confirm there are no extra spaces, missing "Bearer" prefix, or encoding issues in your request headers.
- 3
Check token permissions
If you get 403 (not 401), your token is valid but lacks permissions for the requested action. Confirm the user who generated the token has the correct role (Owner, Admin, Manager) for the API endpoint you are calling.
- 4
Check rate limits
If you send too many requests in a short time, the API returns 429 (Too Many Requests). Check the response headers for rate limit information and add retry logic with backoff to your code.
CRM Sync Issues
If data from Raya or Adam is not appearing in your CRM (or vice versa), the issue is usually field mapping, permissions, or an expired OAuth connection.
- 1
Re-authorize the CRM connection
Go to Dashboard > Integrations and check if your CRM (Salesforce, HubSpot, etc.) shows "Connected". If it shows "Disconnected" or "Expired", click "Re-authorize" to renew the OAuth token.
- 2
Review field mappings
In the CRM integration settings, check that Teammates.ai fields map to the correct CRM fields. A mismatch (e.g., mapping "email" to a CRM "phone" field) causes data to appear in the wrong place or not at all.
- 3
Check CRM user permissions
The CRM user account used for the integration needs read/write access to the objects Teammates.ai syncs (contacts, leads, deals, activities). If the user lacks permissions, syncing silently fails.
- 4
Check sync logs
In Dashboard > Integrations > your CRM, review the sync log. Failed syncs show error details (e.g., "required field missing", "duplicate record", "permission denied") that pinpoint the exact issue.
Getting More Help
If these steps do not resolve your integration issue, contact our support team at hello@teammates.ai or visit teammates.ai/contact. Include the integration type (webhook, API, CRM), error messages or HTTP status codes, and the request/response details if available.
Frequently Asked Questions
Is the Teammates.ai API available on the free plan?▾
How do I test a webhook without triggering real events?▾
Which CRMs does Teammates.ai integrate with?▾
Related Articles
Still need help?
Contact our team