Webhook and API Issues

If your webhooks aren’t receiving data, API calls are returning errors, or integrations are failing to connect, this guide covers the most common issues and how to resolve them.

---

​

Webhooks Not Receiving Data

Symptoms: Your webhook’s “Last Used” column shows “Never” even though you’ve configured an external platform to send data, or contacts aren’t being created from incoming webhook requests. Solutions:

1. Check that the webhook is active. Go to Integrations > Webhooks and look at the status column. The toggle should be green (Active). If it’s gray (Inactive), click the toggle to activate it.
2. Verify the URL is correct. Copy the webhook URL from VozAgent and compare it exactly to what you’ve configured in your external platform. Even a single character difference will cause requests to fail. Use the copy button next to the URL to get an exact copy.
3. Confirm the request format. The external platform must send a POST request with a JSON body. The expected field names are:
   {
     "first_name": "John",
     "last_name": "Doe",
     "phone": "555-123-4567",
     "email": "john@example.com",
     "company": "Acme Inc",
     "message": "Inquiry from website"
   }
   
   Field names are case-sensitive. If your external platform sends firstName instead of first_name, the data won’t be mapped correctly.
4. Send a test request. If you have access to a tool like Postman or cURL, send a test POST request to your webhook URL with sample JSON data. This helps determine whether the issue is with VozAgent or with your external platform’s configuration.
5. Check the signing secret (if used). If you configured your external platform to include a signing secret for verification, make sure the secret matches exactly. The signing secret is only shown once at webhook creation time. If you’ve lost it, delete the webhook and create a new one.

---

​

Webhook Payload Format Issues

Symptoms: Webhook requests are being received (the “Last Used” timestamp updates) but contacts are being created with missing fields. Solutions:

1. Use the correct field names. VozAgent expects these specific field names:

   Field	Expected Name	Required
   First name	first_name	No, but recommended
   Last name	last_name	No, but recommended
   Phone number	phone	Recommended for calling
   Email	email	No
   Company	company	No
   Message/Notes	message	No

2. Send JSON, not form data. The webhook expects Content-Type: application/json in the request headers. If your platform sends form-encoded data (application/x-www-form-urlencoded), the fields won’t be parsed correctly.
3. Map fields in your external platform. Most automation platforms (Zapier, Make, WordPress form plugins) let you map field names. Map their output fields to match VozAgent’s expected field names listed above.

---

​

API Authentication Errors

Symptoms: API calls return a 401 Unauthorized or “Authentication failed” error. Solutions:

1. Use the full API key. The masked preview shown on the API Keys page (e.g., gw_...abc) is not the full key. You need the complete key that was shown once at creation time. If you’ve lost the full key, create a new one from Integrations > API Keys.
2. Check for extra spaces. When pasting your API key, make sure no whitespace was accidentally added before or after the key.
3. Include the key in the correct header. The API key should be sent in the Authorization header as a Bearer token:
   Authorization: Bearer gw_your_full_api_key_here
   
4. Verify the key hasn’t been deleted. Go to Integrations > API Keys and confirm your key still appears in the list. If someone on your team deleted it, you’ll need to create a new one.
5. Create a new key. If nothing else works, create a fresh API key with a descriptive name, copy it immediately, and update your application.

---

​

Common API Error Codes

Here’s what the most common error codes mean and how to resolve them:

---

​

Rate Limiting

Symptoms: API calls return a 429 status code with a “Too Many Requests” message. VozAgent applies rate limits to protect the platform and ensure fair usage. Solutions:

1. Slow down your requests. If you’re making many API calls in rapid succession, add a small delay between them (1-2 seconds).
2. Batch where possible. If you’re creating many contacts, consider using the CSV import feature instead of individual API calls.
3. Check for loops. If you’re using Zapier or Make, make sure your automation isn’t caught in a loop that’s firing requests repeatedly.
4. Implement retry logic. If you’re building a custom integration, add retry logic with exponential backoff — wait 1 second after the first 429, then 2 seconds, then 4 seconds, etc.

---

​

Zapier Connection Issues

Symptoms: Zapier can’t connect to VozAgent, or Zaps are failing with authentication errors. Solutions:

1. Use a fresh API key. Go to Integrations > API Keys and create a new key specifically for Zapier. Give it a descriptive name like “Zapier Integration.”
2. Re-authenticate in Zapier. In your Zapier dashboard, go to My Apps, find VozAgent, and reconnect using the new API key.
3. Check that the Zap is turned on. Zapier Zaps can be paused. Go to your Zap and make sure it’s switched on.
4. Review Zap history. In Zapier, click on the Zap and go to the Zap Runs tab to see if any runs failed and why.

---

​

Webhook Security

If you want to verify that incoming webhook requests are genuinely from your configured source:

1. Use the signing secret. When creating a webhook, VozAgent provides a signing secret. Configure your external platform to include this secret in its requests.
2. Keep the secret secure. Don’t share the signing secret publicly or include it in client-side code.
3. Regenerate if compromised. If you believe the signing secret has been exposed, delete the webhook and create a new one with a fresh secret.

Reminder: The signing secret is only shown once at creation time. If you lose it, delete the webhook and create a new one.

---

​

Next Steps

• Creating and Managing Webhooks — Full guide to setting up webhooks
• API Key Management — Create and manage API keys
• Integrations Overview — All available integrations
• Getting Support — Contact VozAgent support for additional help