Skip to main content
The custom webhook tool lets an ElevenLabs agent call any external URL during a conversation. This allows agents to push data to a CRM, look up order status, submit a lead, or trigger any other HTTP-based integration — without requiring a dedicated Sniko tool for each use case.

​
How it works

Sniko exposes a single endpoint that acts as a proxy between ElevenLabs agents and your external systems: 
POST /tools/custom-webhook
When an agent invokes the tool, ElevenLabs sends the tool call payload to this endpoint. Sniko validates the input, forwards the request to the target webhook_url, and returns the response back to the agent. The agent tool definition is registered globally in ElevenLabs under the name custom_webhook (or similar). Agents configured with this tool can supply the destination URL and payload as parameters in their tool call.

​
Agent tool parameters

The tool accepts the following input from the agent during a conversation:
ParameterRequiredDescription
webhook_urlYesThe target URL to call. Must be a valid URL (max 2048 characters).
methodNoHTTP method: GET, POST, PUT, or PATCH. Defaults to POST.
payloadNoJSON object to send as the request body.
headersNoJSON object of additional HTTP headers to include.
agent_idNoElevenLabs agent ID. Used to look up the account owner for logging.
conversation_idNoElevenLabs conversation ID. Included in the _meta field of every request.

​
Request forwarding

Sniko forwards the request to the target URL with a 15-second timeout. The following headers are always sent: 
Content-Type: application/json
Any headers supplied via the headers parameter are merged on top. Every forwarded request includes a _meta field injected into the payload: 
{
  "your_payload_field": "value",
  "_meta": {
    "agent_id": "agent_abc123",
    "conversation_id": "conv_xyz456",
    "timestamp": "2026-03-25T14:22:00.000000Z",
    "source": "elevenlabs_agent"
  }
}

​
Response

On success: 
{
  "ok": true,
  "tool_call_id": "tc_123",
  "result": {
    "status": "sent",
    "http_status": 200,
    "response": { "...your endpoint response..." },
    "sent_at": "2026-03-25T14:22:00.000000Z"
  }
}
On failure (network error or exception): 
{
  "ok": false,
  "tool_call_id": "tc_123",
  "error": "Webhook request failed: Connection timed out"
}
The target URL receives the full payload you supply, plus the _meta object. Ensure your endpoint can handle or safely ignore the _meta field.

​
Use cases

CRM updates

Push caller information — name, phone, email, issue type — directly into your CRM at the end of a call. The agent collects the data through conversation and triggers the webhook before hanging up.

Order tracking

Have the agent call your order management API mid-conversation to retrieve order status, estimated delivery dates, or return instructions and relay the result back to the caller.

Lead submission

Submit qualified leads to a marketing automation platform or sales tool as soon as the agent has confirmed interest and captured contact details.

Ticket creation

Open a support ticket in Zendesk, Freshdesk, or any REST-based helpdesk by posting the conversation summary and caller details at the end of the call.

​
Simple Webhook (Twilio voice fallback)

The SimpleWebhookController handles a distinct, simpler use case: it is a TwiML endpoint used as a Twilio voice webhook fallback, not a Sniko agent tool. It responds to POST /webhook/simple-voice with TwiML:
  • Inbound calls receive: "Hello! You have reached our test number. This is working correctly!"
  • Outbound calls receive: "Outbound call connected successfully!"
This endpoint is useful for verifying that a Twilio phone number is correctly configured before attaching it to a full agent workflow.

​
Security considerations

The custom webhook tool does not restrict which URLs agents can call. An agent can target any reachable URL. If you want to limit which domains are allowed, implement URL validation in your agent’s system prompt or add middleware to the /tools/custom-webhook route.
Data collected during a conversation (names, phone numbers, emails) is forwarded directly to the target URL. Ensure the target endpoint uses HTTPS and that you have consent to transmit the caller’s information to third parties.
Requests to the target URL time out after 15 seconds. If the target does not respond in time, the agent receives an error response and can handle it according to its system prompt instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us