Skip to main content

​
Webhook Mappings

Webhook Mappings are a no-code integration system that automatically transforms incoming data from external services into contacts within AgentVoice. They enable seamless data flow from third-party platforms (CRMs, forms, marketing tools, etc.) into your AgentVoice contact database without writing custom integration code.

​
How It Works

1

Create a Mapping

Define how incoming data fields should map to contact fields in your system
2

Get a Webhook URL

Each mapping generates a unique webhook endpoint
3

Configure External System

Point your external service to POST data to this URL
4

Automatic Contact Creation

When data arrives, contacts are created automatically based on your mapping rules

​
Creating a Webhook Mapping

Navigate to Settings > API > Webhook Mappings and click Create Mapping. You’ll configure:
  • Mapping Name - A descriptive name for this mapping (e.g., “EMR Patient Webhook”)
  • Action Type - Currently supports “Create Contact” (more action types coming soon)
  • Field Mappings - How source fields map to target contact fields
  • Static Values - Default values applied to all incoming contacts
  • Static Tags - Tags automatically applied to contacts from this mapping

​
Key Features

​
Field Mapping

Transform source fields from external systems to target fields in AgentVoice. Map custom field names from your external service to standard contact properties.

​
Static Values

Set default values for specific fields that apply to all incoming data. Useful for adding source identifiers, campaign names, or other metadata.

​
Static Tags

Automatically tag contacts created through specific mappings. This helps organize and segment contacts based on their source.

​
Active/Inactive States

Enable or disable mappings without deleting them. Temporarily pause data intake while maintaining your configuration.

​
Multiple Mappings

Create different mappings for different data sources. Each mapping gets its own unique webhook URL and configuration.

​
Managing Your Mappings

Once created, each mapping displays:
  • Mapping Name and status (Active/Inactive)
  • Webhook URL - Copy this to use in your external system
  • Map ID - Unique identifier for the mapping
  • Setup Instructions - Quick reference for authentication parameters

​
Authentication Setup

You’ll need three values to authenticate webhook requests. You can provide them via Query Parameters, Request Body, or HTTP Headers.
  • orgId - Your organization ID
  • apiKey - API key from the API Keys tab
  • mapId - Unique mapping ID (already set in webhook URL)

​
Authentication Methods

Easiest Method - Use the webhook URL as shown with authentication in the URL.
POST https://api.agentvoice.com/api/contacts/flex?orgId=YOUR_ORG_ID&apiKey=YOUR_API_KEY&mapId=...
Content-Type: application/json

{
  "firstName": "John",
  "phone": "+1234567890"
}
This method works best with most form builders and automation tools.
Choose the authentication method that works best with your webhook provider. Most form builders and automation tools work best with query parameters, while custom integrations may prefer headers for better security.

​
Use Cases

Webhook Mappings are ideal for:
  • Lead Capture - Import leads from landing page forms automatically
  • CRM Synchronization - Sync customer data from your CRM in real-time
  • Event Registrations - Capture event registrations and trigger follow-up
  • Marketing Automation - Integrate with marketing automation platforms
  • Scheduling Integration - Connect scheduling systems to trigger automated outreach
  • Multi-Platform Data Collection - Aggregate contacts from multiple sources with different mappings

​
Best Practices

Name your mappings clearly to identify the data source at a glance. For example: “Typeform Lead Capture” or “Salesforce Contact Sync”.
Before connecting your production system, test the webhook with sample data to verify field mappings work correctly.
Apply source-specific tags to contacts so you can easily segment and identify where contacts originated.
Treat API keys as sensitive credentials. Use environment variables or secure configuration management in your external systems.
Periodically review inactive mappings and delete those no longer needed to keep your workspace organized.

​
Troubleshooting

If contacts aren’t being created:
  1. Verify Authentication - Ensure your orgId, apiKey, and mapId are correct
  2. Check Mapping Status - Confirm the mapping is set to “Active”
  3. Validate Data Format - Ensure incoming data matches expected field names
  4. Review Field Mappings - Verify required fields (like phone number) are properly mapped
  5. Test the URL - Use a tool like Postman to test the webhook URL directly
Contact creation requires at minimum a valid phone number. Ensure your mapping includes the phone field from your data source.