Skip to main content
Webhooks let you receive contact data from external platforms and push it directly into VozAgent. When you create a webhook, VozAgent generates a unique URL that external tools — like WordPress forms, Zapier, or Make — can send data to. Any contact data sent to that URL is automatically added to your VozAgent contact list.

​
What Are Incoming Webhooks?

An incoming webhook is a URL that accepts data from outside VozAgent. Unlike integrations that connect to a specific platform, webhooks are generic — any system that can send an HTTP request can push data to your webhook URL. Common use cases include:
  • WordPress contact forms — when someone fills out a form on your website, the data is sent to VozAgent
  • Zapier automations — trigger a Zap that sends new leads from another app to VozAgent
  • Make scenarios — route data from any Make module to your VozAgent contact list
  • Custom applications — any app or script that can make HTTP POST requests

​
Getting to Webhooks

  1. Go to Integrations in your sidebar
  2. Click the Webhooks tab at the top of the page
If you don’t have any webhooks yet, you’ll see an empty state with a message: “No Webhooks Yet” and a prompt to create your first one.

​
Creating a Webhook

  1. Click the Create Webhook button (either in the empty state or in the top-right corner if you already have webhooks)
  2. In the dialog that appears, enter a Webhook Name — give it a descriptive name so you can identify where contacts are coming from (for example, “WordPress Contact Form” or “Zapier Lead Sync”)
  3. Click Create Webhook

​
After Creation

Once the webhook is created, a dialog appears with two important values:
  • Webhook URL — the URL you will configure in your external platform to send data to
  • Signing Secret — an optional secret for verifying that incoming requests are legitimate
Both values have a copy button next to them for easy copying. Important: The signing secret is only shown once at creation time. Make sure to copy it before closing the dialog. If you lose it, you will need to create a new webhook.

​
Example Payload

The dialog also shows an example of the JSON data format your external platform should send: 
{
  "first_name": "John",
  "last_name": "Doe",
  "phone": "555-123-4567",
  "email": "john@example.com",
  "company": "Acme Inc",
  "message": "Inquiry from website"
}
Your external platform should send a POST request to the webhook URL with a JSON body containing the contact fields you want to capture.

​
Managing Your Webhooks

All your webhooks are displayed in a table with the following columns:
ColumnDescription
NameThe descriptive name you gave the webhook
Webhook URLThe unique URL for receiving data (with a copy button)
StatusShows Active (green badge) or Inactive (gray badge)
Last UsedThe date and time the webhook last received data, or “Never” if it hasn’t been used yet
ActionsToggle and delete buttons

​
Activating and Deactivating Webhooks

Each webhook has a toggle button in the Actions column:
  • Green toggle (Active) — the webhook is accepting incoming data
  • Gray toggle (Inactive) — the webhook is paused and will reject incoming data
Click the toggle to switch between active and inactive. Deactivating a webhook is useful when you want to temporarily stop receiving data without deleting the webhook entirely.

​
Copying a Webhook URL

Click the copy icon next to any webhook URL in the table to copy it to your clipboard. A confirmation toast appears when the URL is successfully copied.

​
Deleting a Webhook

To delete a webhook:
  1. Click the trash icon in the Actions column next to the webhook
  2. A confirmation dialog appears showing the webhook name
  3. Click Delete to confirm
Deleting a webhook is permanent. Any external platform still pointing to the deleted webhook URL will receive errors when sending data.

​
Automatic Field Mapping

One of the most powerful features of VozAgent webhooks is automatic field mapping. You do not need to worry about matching your form’s field names exactly to VozAgent’s schema — the system recognizes dozens of common field name variations and maps them automatically. For example, all of the following field names will be correctly recognized as a phone number:
  • phone, phone_number, phoneNumber, mobile, telephone, cell, cellphone, tel

​
Supported Field Mappings

VozAgent FieldRecognized Names
First namefirst_name, firstName, fname, given_name
Last namelast_name, lastName, lname, surname, family_name
Full namename, full_name, fullName, contact_name (automatically split into first and last)
Phonephone, phone_number, phoneNumber, mobile, telephone, cell, tel
Emailemail, email_address, emailAddress, mail
Companycompany, company_name, companyName, organization, business
Job titlejob_title, jobTitle, title, position, role
Notes/Messagenotes, message, comment, comments, inquiry, description, body
Tagstags, tag, labels, categories
Addressaddress, street, street_address, and specific variants like home_address, service_address, property_address
City, state, ZIPcity, state, province, zip, zip_code, postal_code

​
Name Splitting

If your form sends a single name field (like “John Doe”), VozAgent automatically splits it into first name (“John”) and last name (“Doe”). You do not need to create separate first name and last name fields in your form.

​
Extra Form Fields

Any fields in your form that do not match a known contact field are not lost. VozAgent captures them as a note attached to the contact. For example, if your form includes fields like bedrooms, square_footage, or preferred_date, those values are saved as a note on the contact record with a label like:
Additional form details: Bedrooms: 3 Square Footage: 1500 Preferred Date: Next week
This means you can use any form with any fields, and VozAgent will preserve all the data.

​
Auto-Call: Trigger a Call When a Form is Submitted

The most powerful webhook feature is auto-call — when someone fills out a form on your website, VozAgent can automatically call them back with your AI assistant. This turns every form submission into an instant follow-up call.

​
How Auto-Call Works

  1. A visitor fills out a form on your website (for example, a “Request a Quote” form).
  2. The form sends the data to your VozAgent webhook URL.
  3. VozAgent creates a new contact from the form data.
  4. After a configurable delay (default: 30 seconds), VozAgent’s AI assistant automatically calls the contact.
  5. The assistant greets them by name, references their form submission, and handles the conversation based on the assistant’s configuration.

​
Setting Up Auto-Call

Auto-call is configured per webhook. When creating or editing a webhook:
  1. Enable the Auto-Call toggle.
  2. Select which outbound assistant should make the call.
  3. Set the delay — how many seconds to wait after the form submission before calling. A short delay (15-30 seconds) means the contact is called while they are still at their computer. A longer delay (a few minutes) gives them time to move on but still catches them promptly.
  4. Choose whether to respect business hours — when enabled, calls that arrive outside your business hours are queued until the next business window opens.

​
What the Contact Experiences

The contact’s phone rings and they hear your AI assistant introduce itself:
“Hi [name], this is [assistant name] calling from [your company]. I saw you reached out about [their project type] — I’d love to help get you on the calendar for a free estimate.”
The assistant has access to all the form data, so it can reference what the contact was asking about. If the form included extra fields (like “service type: roof repair” or “bedrooms: 3”), the assistant uses those details naturally in the conversation.

​
Auto-Call for Returning Contacts

If someone submits a form but their phone number already exists in your contacts, VozAgent still triggers the auto-call. This handles the case where a returning customer fills out a form again — they get called back just like a new lead.

​
Duplicate Detection

VozAgent automatically checks for duplicate contacts when a webhook receives data. Duplicates are detected by matching phone number or email address.
  • If a matching contact already exists, the webhook returns a message indicating the duplicate and does not create a new contact.
  • If auto-call is enabled, the existing contact still receives the auto-call — so returning customers who submit your form again will still get a callback.

​
Lead Source Tracking

VozAgent tracks where each contact came from. When data arrives through a webhook, the source is automatically set to the webhook name (for example, “webhook:WordPress Contact Form”). You can also pass structured lead source information in your form data for more detailed tracking:
FieldPurposeExample
lead_source_platform or utm_sourceThe platform or traffic sourcegoogle, facebook, instagram
lead_source_campaign or utm_campaignThe specific campaignspring-sale-2025
lead_source_url or landing_pageThe URL where the form was submittedhttps://yoursite.com/contact
This information appears on the contact’s detail page and is available to the AI assistant during calls.

​
Using Your Webhook URL

Once you have your webhook URL, configure it in your external platform:

​
WordPress Forms

If you use a form plugin (like WPForms, Gravity Forms, or Contact Form 7), look for a webhook or HTTP POST option in the form’s settings. Paste your VozAgent webhook URL there. Thanks to automatic field mapping, you do not need to rename your form fields — VozAgent will recognize common field names automatically.

​
Zapier

In Zapier, use a Webhooks by Zapier action and configure it to send a POST request to your VozAgent webhook URL. Map the fields from your trigger app to any of the recognized field names listed above.

​
Make

In Make, use an HTTP - Make a request module. Set the method to POST, paste your webhook URL, and configure the body with the contact data fields.

​
Any Other Platform

Any system that can send an HTTP POST request with a JSON body can use your webhook URL. The minimum required field is a name (first_name or name). A phone number is required if you want to use auto-call.

​
Signing Secret (Optional)

The signing secret adds a layer of security to verify that incoming webhook requests are genuinely from your configured source and have not been tampered with.

​
How It Works

When your external platform sends a request, it should include a signature in the x-vozagent-signature header. The signature format is: 
t=1234567890,v1=abc123def456...
Where t is the Unix timestamp and v1 is the HMAC-SHA256 hash of the timestamp and request body, signed with your webhook’s signing secret. VozAgent validates:
  1. The signature matches the expected hash.
  2. The timestamp is within 5 minutes of the current time (to prevent replay attacks).

​
When You Need It

  • Server-to-server integrations — If your backend sends webhook requests, use the signing secret to ensure only your server can push data to VozAgent.
  • Browser-based forms — If your website form submits directly to the webhook URL, you can skip the signing secret since the secret would need to be exposed in client-side code. The webhook still works without it.
If you do not send the x-vozagent-signature header, VozAgent accepts the request without signature validation. Signature verification only activates when the header is present.

​
Troubleshooting

Webhook not receiving data — Make sure the webhook status is Active. Check that the external platform is sending a POST request to the correct URL with a JSON body and the Content-Type: application/json header. “Last Used” shows “Never” — The webhook has not received any data yet. Verify the URL is correctly configured in your external platform and try sending a test request. Missing contact fields — Check the Automatic Field Mapping section above. VozAgent recognizes many field name variations, but the field names are case-sensitive. If your form uses an unusual field name, the data will still be captured as a note on the contact. Duplicate contact error (409) — The phone number or email already exists in your contacts. This is expected behavior. If auto-call is enabled, the existing contact will still receive the callback. Auto-call not triggering — Make sure auto-call is enabled on the webhook, an outbound assistant is selected, and the contact has a phone number. Also check that your business hours settings allow calls at the current time (if “Respect Business Hours” is enabled). Lost signing secret — The signing secret is only shown once when the webhook is created. If you need a new one, delete the webhook and create a new one.