Webhooks
Real-time events keep your systems synchronized. The platform can send webhook notifications for conversation events, task completions, and other important activities.
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
Create a Mapping
Define how incoming data fields should map to contact fields in your system
Get a Webhook URL
Each mapping generates a unique webhook endpoint
Configure External System
Point your external service to POST data to this URL
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.
Include authentication parameters in your JSON payload.
POST https://api.agentvoice.com/api/contacts/flex
Content-Type: application/json
{
"orgId": "YOUR_ORG_ID",
"apiKey": "YOUR_API_KEY",
"mapId": "...",
"firstName": "John",
"phone": "+1234567890"
}Useful when your webhook provider allows custom JSON payloads.
Most Secure - Pass authentication in custom headers.
POST https://api.agentvoice.com/api/contacts/flex
Content-Type: application/json
x-org-id: YOUR_ORG_ID
x-api-key: YOUR_API_KEY
x-map-id: ...
{
"firstName": "John",
"phone": "+1234567890"
}Preferred for custom integrations where you control the HTTP client.
Tip
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
Troubleshooting
If contacts aren't being created:
- Verify Authentication - Ensure your orgId, apiKey, and mapId are correct
- Check Mapping Status - Confirm the mapping is set to "Active"
- Validate Data Format - Ensure incoming data matches expected field names
- Review Field Mappings - Verify required fields (like phone number) are properly mapped
- 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.