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

# Webhook Filtering

> Route webhook events to specific endpoints based on agent

# Webhook Filtering

By default, a webhook endpoint receives events from all agents in your account. Agent filtering lets you scope an endpoint to only receive events from the agents you choose.

## Why Filter by Agent?

Common scenarios:

* **Multi-CRM setup** different agents serve different CRMs, each needs its own webhook
* **Team separation** sales and support agents route to different backends
* **Testing** point test agent events to a staging endpoint without affecting production

## Setting Up Agent Filtering

In the dashboard, open **Connecter > Webhooks**, add or edit a webhook, and use **Agent Filter** on the Endpoint step (click **Customize**, then add agents). Leave it on "All agents (default)" for no filter. Through the API, set the `agentIds` field (up to 50 agent IDs) when creating a webhook endpoint:

```bash theme={null}
curl -X POST https://client-backend.oktivo.com/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://salesforce.your-company.com/webhooks/oktivo",
    "eventTypes": ["call.analysis_ready", "call.completed"],
    "agentIds": ["agent_sales_qualifier"]
  }'
```

This endpoint will only receive events from the `agent_sales_qualifier` agent.

## Example: Multi-CRM Setup

```
Agent: Sales Qualifier
  └── Webhook → https://salesforce.company.com/webhooks/oktivo

Agent: Support Follow-up  
  └── Webhook → https://zendesk.company.com/webhooks/oktivo

Agent: Appointment Setter
  └── Webhook → https://calendly-integration.company.com/webhooks/oktivo
```

Each CRM only receives events relevant to its agent.

## Creating Multiple Filtered Endpoints

You can create as many filtered endpoints as needed:

```bash Sales agent webhook theme={null}
curl -X POST https://client-backend.oktivo.com/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sales-crm.company.com/hooks/oktivo",
    "eventTypes": ["call.analysis_ready"],
    "agentIds": ["agent_sales_001"]
  }'
```

```bash Support agent webhook theme={null}
curl -X POST https://client-backend.oktivo.com/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://support-system.company.com/hooks/oktivo",
    "eventTypes": ["call.ended", "call.analysis_ready"],
    "agentIds": ["agent_support_001"]
  }'
```

## Catch-All Endpoint

Create an endpoint without `agentIds` to receive events from all agents:

```bash theme={null}
curl -X POST https://client-backend.oktivo.com/webhooks/endpoints \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://analytics.company.com/hooks/all-calls",
    "eventTypes": ["call.ended", "call.completed"]
  }'
```

This is useful for analytics, logging, or audit purposes.

## Updating an Existing Endpoint's Filter

Change the agent filter on an existing endpoint:

```bash theme={null}
curl -X PUT https://client-backend.oktivo.com/webhooks/endpoints/{webhookId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentIds": ["agent_new_qualifier"]
  }'
```

Send `"agentIds": []` to remove the filter and receive events from all agents.

## Combining with Event Type Filtering

Agent filtering works alongside event type filtering. The endpoint only receives events that match **both** criteria:

* Event type is in the `eventTypes` array **AND**
* The event's agent is one of the endpoint's `agentIds` (or no agent filter is set)

## Best Practices

* Use filtered endpoints for production integrations to avoid processing irrelevant events
* Keep a catch-all endpoint for monitoring and debugging
* Name your endpoints descriptively (use the `description` field) so it's clear which agent maps where
* When retiring an agent, remember to delete or update its webhook endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.