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 a specific agent.

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

Set the agentId field when creating a webhook endpoint:

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"],
    "agentId": "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:

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"],
    "agentId": "agent_sales_001"
  }'

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"],
    "agentId": "agent_support_001"
  }'

Catch-All Endpoint

Create an endpoint without agentId to receive events from all agents:

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:

curl -X PUT https://client-backend.oktivo.com/webhooks/endpoints/{webhookId} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_new_qualifier"
  }'

Set agentId to null 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 matches the endpoint’s agentId (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

Getting Started

Core Concepts

Guides

Webhook Filtering

Webhook Filtering

Why Filter by Agent?

Setting Up Agent Filtering

Example: Multi-CRM Setup

Creating Multiple Filtered Endpoints

Catch-All Endpoint

Updating an Existing Endpoint’s Filter

Combining with Event Type Filtering

Best Practices

​Webhook Filtering

​Why Filter by Agent?

​Setting Up Agent Filtering

​Example: Multi-CRM Setup

​Creating Multiple Filtered Endpoints

​Catch-All Endpoint

​Updating an Existing Endpoint’s Filter

​Combining with Event Type Filtering

​Best Practices

Webhook Filtering

Why Filter by Agent?

Setting Up Agent Filtering

Example: Multi-CRM Setup

Creating Multiple Filtered Endpoints

Catch-All Endpoint

Updating an Existing Endpoint’s Filter

Combining with Event Type Filtering

Best Practices