Dynamic Tool Configuration: Pre-tool webhooks allow you to fetch contextual data and customize tool parameters in real-time before specific tools are executed during calls.

​
Overview

Showing the configuration for pre-tool webhook Pre-tool webhooks enable targeted data injection for specific tools during active calls. When certain tools are about to execute, Openmic can optionally send tool details to your webhook endpoint, and your system responds with dynamic variables that customize the tool’s behavior.

Tool-Specific Data

Fetch relevant information and parameters specific to the tool being executed.

Runtime Customization

Modify tool parameters dynamically based on call context and external data sources.

​
Configuration Options

​
Webhook URL Selection

Pre-tool webhooks support flexible URL configuration:

Use Pre-Call URL

To reuse your existing pre-call webhook endpoint

Dedicated URL

Specify a dedicated URL for a tool-specific webhook endpoint
Pre-tool webhooks are tool-specific and must be enabled individually for each tool through the configuration.

​
Request Specification

​
HTTP Method and Timeout

Openmic sends a POST request to your configured webhook URL with:
  • Content-Type: application/json
  • Timeout: 3 seconds per attempt
  • User-Agent: Openmic-Webhook/1.0
Unlike pre-call webhooks, pre-tool webhook failures do not terminate the call. Tools will execute with original parameters if the webhook fails.

​
Request Payload

{
	"event": "tool",
	"tool_name": "calendar_booking",
	"tool": {
		"direction": "inbound",
		"bot_id": "cmdx5w8oc0005q671s3cbg063",
		"from_number": "+16167948654",
		"to_number": "+916297653534",
	}
}

​
Payload Fields

FieldTypeRequiredDescription
eventstringYesAlways "tool" for pre-tool webhooks
tool_namestringYesName of the tool being executed
tool.directionstringYesCall direction: "inbound" or "outbound"
tool.bot_idstringYesUnique identifier for the bot/session
tool.from_numberstringYesCaller’s phone number in E.164 format
tool.to_numberstringYesCallee’s phone number in E.164 format

​
Tool Names

  • calendar_check
  • calendar_booking
  • transfer_call

​
Expected Response

​
Success Response

Your webhook must return a 200 status code with a JSON response containing dynamic variables: 
{
	"tool": {
		"dynamic_variables": {
			"transfer_number": "+15551234567",
			"booking_preference": "morning",
			"calendar_timezone": "America/New_York",
			"priority_level": "high"
		}
	}
}

​
Response Structure

FieldTypeRequiredDescription
toolobjectYesContainer for tool-related data
tool.dynamic_variablesobjectYesKey-value pairs of variables to inject into the tool
Variable Merging: Pre-tool dynamic variables are merged with existing call variables, with pre-tool variables taking precedence for conflicts.

​
Retry Logic and Error Handling

​
Retry Configuration

Max Attempts

3 total attempts 1 initial request + 2 retries

Timeout

3 seconds Per individual request attempt

Backoff Strategy

Exponential delays 1s, 2s, 3s between retries

​
Retry Triggers

Openmic retries your webhook in these scenarios:
  • Timeout: No response within 3 seconds
  • HTTP Errors: 4xx or 5xx status codes
  • Network Errors: Connection failures or DNS resolution issues
  • Invalid JSON: Malformed response body

​
Failure Handling

Graceful Degradation: If all webhook attempts fail, the tool will execute using its original parameters without dynamic variables.
Pre-tool webhooks are designed for graceful degradation. When webhook calls fail:
  1. The failure is logged for debugging purposes
  2. The tool continues execution with its original static parameters
  3. Any existing call-level dynamic variables remain available
  4. The call continues normally without interruption

​
Examples

// Example transfer number lookup function
async function getTransferNumber(fromNumber) {
    // Pretend we're fetching from a transfer number lookup API
    console.log(`Looking up transfer number for: ${fromNumber}`);
    return {
        transfer_number: '+1234567890' // match variable name from docs
    };
}

app.post('/webhook/pre-tool', async (req, res) => {
  const { tool_name, tool } = req.body;
  console.log(`🔧 Pre-tool webhook for: ${tool_name}`, tool);

  try {
    if (tool_name === 'transfer_call') {
      const transferNumber = await getTransferNumber(tool.from_number);

      return res.json({
        tool: {
          dynamic_variables: transferNumber
        }
      });
  	}

    // Default: no customization for other tools
    return res.json({
      tool: {
        dynamic_variables: {}
      }
    });
  } catch (err) {
    console.error('❌ Failed to fetch tool data', err);

    // Graceful degradation: return empty vars if lookup fails
    return res.json({
      tool: {
        dynamic_variables: {}
      }
    });
  }
});