> ## Documentation Index
> Fetch the complete documentation index at: https://www.agentvoice.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Create a Mapping">
    Define how incoming data fields should map to contact fields in your system
  </Step>

  <Step title="Get a Webhook URL">
    Each mapping generates a unique webhook endpoint
  </Step>

  <Step title="Configure External System">
    Point your external service to POST data to this URL
  </Step>

  <Step title="Automatic Contact Creation">
    When data arrives, contacts are created automatically based on your mapping rules
  </Step>
</Steps>

### 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

<Tabs>
  <Tab title="Query Parameters">
    **Easiest Method** - Use the webhook URL as shown with authentication in the URL.

    ```http theme={null}
    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.
  </Tab>

  <Tab title="Request Body">
    Include authentication parameters in your JSON payload.

    ```http theme={null}
    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.
  </Tab>

  <Tab title="HTTP Headers">
    **Most Secure** - Pass authentication in custom headers.

    ```http theme={null}
    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.
  </Tab>
</Tabs>

<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.
</Tip>

### 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

<AccordionGroup>
  <Accordion title="Use Descriptive Mapping Names">
    Name your mappings clearly to identify the data source at a glance. For example: "Typeform Lead Capture" or "Salesforce Contact Sync".
  </Accordion>

  <Accordion title="Test with Sample Data">
    Before connecting your production system, test the webhook with sample data to verify field mappings work correctly.
  </Accordion>

  <Accordion title="Use Static Tags for Organization">
    Apply source-specific tags to contacts so you can easily segment and identify where contacts originated.
  </Accordion>

  <Accordion title="Secure Your API Keys">
    Treat API keys as sensitive credentials. Use environment variables or secure configuration management in your external systems.
  </Accordion>

  <Accordion title="Monitor Inactive Mappings">
    Periodically review inactive mappings and delete those no longer needed to keep your workspace organized.
  </Accordion>
</AccordionGroup>

### 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

<Note>
  Contact creation requires at minimum a valid phone number. Ensure your mapping includes the phone field from your data source.
</Note>