Agent Tools and Webhooks

Overview

Agents talk to your server in two ways. Both are HTTPS endpoints that you set on the agent, and 60db signs every request.

Direction	When	Your field	Your reply
Tool call	The agent needs data or an action during a call	`tool_webhook_url`	JSON, within about 6 seconds. The agent speaks it
Event	A call ends, or its recording is ready	`event_webhook_url`	Any `2xx` status. The body is ignored

Both use the same signing scheme. See Verify signatures.

Define tools

Add tools to an agent with tools. Each tool is described with JSON Schema, so the agent knows when to use it and what arguments to send.

{
  "name": "book_table",
  "description": "Book a table for guests. Call this only after the caller gives a date, time and party size.",
  "parameters": {
    "type": "object",
    "properties": {
      "date": { "type": "string", "description": "YYYY-MM-DD" },
      "time": { "type": "string", "description": "HH:MM, 24-hour" },
      "guests": { "type": "integer", "minimum": 1 }
    },
    "required": ["date", "time", "guests"]
  }
}

Rule	Limit
`name`	Letters, digits and underscores. Must not start with a digit. Up to 64 characters. Unique per agent. `transfer_call` and `forget_me` are reserved
`description`	1 to 500 characters
`parameters`	JSON Schema with `"type": "object"`. Up to 4 KB of JSON
Tools per agent	Up to 16
`tool_webhook_url`	Required when the agent has tools

Set the URL on the agent when you create it or later with PATCH /agents/{agentId}. A URL that is not https:// returns 400 VALIDATION_ERROR. A URL on port other than 443, one with credentials or a fragment, or one that resolves to a private or loopback address returns 422 UNSAFE_WEBHOOK_URL.

Tool call request

When the agent calls a tool, 60db sends a POST to your tool_webhook_url:

POST /your/tool/path HTTP/1.1
Content-Type: application/json
X-60db-Event: tool.call
X-60db-Timestamp: 1762165200
X-60db-Signature: v1=3f2a…

{
  "call_id": "6b1f0c52-4d7e-4b8a-9d3e-2a1c8e7f0a11",
  "agent_id": "9c2e1d7a-0b3f-4e6a-8f1d-5a7b9c0e2d44",
  "tool": "book_table",
  "tool_call_id": "call_8f21c0",
  "turn": 3,
  "arguments": { "date": "2026-11-05", "time": "19:30", "guests": 4 },
  "metadata": { "crm_lead_id": "L-1042" }
}

Field	Meaning
`call_id`	The call’s id. `null` only if the call could not be matched
`agent_id`	The agent’s id
`tool`	The tool name you defined
`tool_call_id`	Unique id for this tool call. Use it to dedupe
`turn`	Conversation turn number
`arguments`	The arguments the agent chose. Validate them before you act
`metadata`	The `metadata` you passed when you placed the call

Your reply

Reply with a JSON object within about 6 seconds. The agent speaks what it needs from that object.

{ "available": true, "slots": ["19:30", "20:00"] }

If your reply is late, not JSON, too large or not 2xx, the agent receives an error object instead of your reply. The call continues.

What your endpoint does	What the agent receives
Returns `2xx` with a JSON object	Your JSON object
Takes longer than about 6 seconds	`{"error": "tool_unavailable", "reason": "timeout"}`
Returns a non-`2xx` status	`{"error": "tool_unavailable", "reason": "http_500"}` (the status code varies)
Returns a body that is not JSON	`{"error": "tool_unavailable", "reason": "not_json"}`
Returns more than 16 KB	`{"error": "tool_unavailable", "reason": "too_large"}`
Cannot be reached	`{"error": "tool_unavailable", "reason": "unreachable"}`

Other reason values: unsafe_url (the address failed the safety check at call time). Notes:

No retries. A tool call is sent once. If it fails, the agent gets the error.
Duplicate calls. If the same tool_call_id arrives again, 60db returns the saved answer. Your endpoint is not called a second time.
Tool log. Every tool call is logged with its arguments, your reply, status code and latency. See the Tool log in the dashboard, or GET /agents/{agentId}/tool-events for the last 50. Logs are kept 30 days.

Example tool endpoint (Node.js)

import http from 'node:http';
import { verifyWebhookSignature } from '60db-service';

const SECRET = process.env.SIXTYDB_WEBHOOK_SECRET; // whsec_… from create or rotate

http.createServer((req, res) => {
  const chunks = [];
  req.on('data', (c) => chunks.push(c));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);
    const ok = verifyWebhookSignature({
      rawBody: raw,
      signature: req.headers['x-60db-signature'],
      timestamp: req.headers['x-60db-timestamp'],
      secret: SECRET,
    });
    if (!ok) { res.writeHead(401).end(); return; }

    const msg = JSON.parse(raw.toString('utf8'));
    const result = msg.tool === 'book_table'
      ? { booked: true, reference: `BK-${msg.tool_call_id.slice(-6)}` }
      : { error: 'unknown_tool' };
    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(result));
  });
}).listen(8080);

Example tool endpoint (Python)

import json
from http.server import BaseHTTPRequestHandler, HTTPServer
from sixtydb import verify_webhook_signature
import os

SECRET = os.environ["SIXTYDB_WEBHOOK_SECRET"]  # whsec_… from create or rotate

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        ok = verify_webhook_signature(raw, self.headers.get("X-60db-Signature"),
                                      self.headers.get("X-60db-Timestamp"), SECRET)
        if not ok:
            self.send_response(401); self.end_headers(); return
        msg = json.loads(raw)
        result = {"booked": True, "reference": f"BK-{msg['tool_call_id'][-6:]}"} if msg["tool"] == "book_table" \
            else {"error": "unknown_tool"}
        body = json.dumps(result).encode()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(body)

HTTPServer(("", 8080), Handler).serve_forever()

Call transfer

Besides webhook (JSON) tools, an agent can hand a call to a person. Set transfer_targets on the agent, or per call in overrides.transfer_targets:

"transfer_targets": [
  { "name": "Sales", "numbers": ["+919876543210", "+919876543211"] },
  { "name": "Support", "numbers": ["+14155550100"] }
]

How it works. The name is what callers ask for (“connect me to Sales”), so use a team name callers would say, not “Call Transfer”. The numbers are tried in turn until someone answers. The first target is also used when a caller asks for “a person”. 60db adds the matching instruction to your agent automatically; you don’t need to write it in the script.

Each group becomes a function the agent can use, transfer_to_<name> (Sales Team becomes transfer_to_sales_team). The agent only picks a name; the numbers stay with you.
The first group is used when a caller asks for a person without saying which team.
With several numbers in a group, they are tried in turn. If one fails or refuses, the next is tried, and the call stays with the agent if none answers.
Up to 10 groups of up to 10 E.164 numbers. Names must be distinct, and webhook tools cannot be named transfer_call or start with transfer_to_.
summary.transferred on the call says whether it was handed over. The transferred leg is billed as Dialer minutes on your line.

In the dashboard, open the agent’s Tools & webhooks tab, choose Add tool, then Call transfer.

Events

When a call ends, or its recording is ready, 60db sends an event to event_webhook_url.

Event	Sent when	`data`
`call.completed`	The call ended normally	The call object, as returned by Get call
`call.failed`	The call did not connect, or ended with an error	The call object, as returned by Get call
`recording.ready`	A recorded call’s audio and transcript are stored	See below

Events are sent only when the agent has an event_webhook_url. recording.ready is sent only for recorded calls. It can arrive after call.completed.

Envelope

Every event has the same envelope:

{
  "id": "0f7a3c1e-9b2d-4e5f-a6c7-1d2e3f4a5b6c",
  "type": "call.completed",
  "created_at": "2026-11-03T10:17:42.000Z",
  "data": {
    "id": "6b1f0c52-4d7e-4b8a-9d3e-2a1c8e7f0a11",
    "agent_id": "9c2e1d7a-0b3f-4e6a-8f1d-5a7b9c0e2d44",
    "agent_name": "Front desk",
    "phone_line_id": "2d8e4f10-6a3b-4c9d-8e7f-0b1a2c3d4e5f",
    "direction": "outbound",
    "to": "+919999999999",
    "from": "+919876543210",
    "status": "completed",
    "reason": null,
    "duration_secs": 62,
    "started_at": "2026-11-03T10:16:30.000Z",
    "connected_at": "2026-11-03T10:16:38.000Z",
    "ended_at": "2026-11-03T10:17:40.000Z",
    "record": true,
    "has_recording": true,
    "has_transcript": true,
    "summary": { "turns": 6, "tool_calls": 1, "tool_failures": 0 },
    "cost": { "runtime_usd": 0, "runtime_billing_status": "skipped" },
    "source": "api",
    "metadata": { "crm_lead_id": "L-1042" },
    "created_at": "2026-11-03T10:16:30.000Z"
  }
}

recording.ready carries the recording details and transcript, not a download link:

{
  "id": "5e4d3c2b-1a09-4f8e-b7d6-c5a4b3e2f1d0",
  "type": "recording.ready",
  "created_at": "2026-11-03T10:17:55.000Z",
  "data": {
    "call_id": "6b1f0c52-4d7e-4b8a-9d3e-2a1c8e7f0a11",
    "recording": {
      "bytes": 1978284,
      "content_type": "audio/wav",
      "audio_path": "/agents/calls/6b1f0c52-4d7e-4b8a-9d3e-2a1c8e7f0a11/recording"
    },
    "transcript": { "turns": [{ "speaker": "agent", "text": "Hello, Juniper Kitchen.", "at_ms": 0 }] }
  }
}

Download the audio with your API key at https://api.60db.ai{audio_path} (add ?download=1 to save it as a file).

Event headers

Header	Meaning
`X-60db-Event`	Event type, for example `call.completed`
`X-60db-Event-Id`	Unique delivery id. Same as the envelope `id`. Use it to dedupe
`X-60db-Delivery-Attempt`	Attempt number, starting at `1`
`X-60db-Timestamp`	Unix time in seconds when the request was signed
`X-60db-Signature`	`v1=` plus the hex HMAC, see below

Retries

Any response other than 2xx, a timeout or a network error counts as a failed attempt. Redirects count as failures too.
Reply quickly. Acknowledge with 2xx before doing slow work. A reply slower than about 5 seconds counts as a timeout.
60db makes up to 5 attempts. It waits 30 seconds, then 1, 2 and 4 minutes between them.
After the fifth failed attempt the event is marked failed and is not sent again.
Events can arrive more than once, for example if your response was lost. Process each X-60db-Event-Id once.
Events can arrive out of order. Read the call again with GET /agents/calls/{callId} if you need its current state.

Verify signatures

Verify every tool call and event before you act on it.

Header	Value
`X-60db-Timestamp`	Unix time in seconds
`X-60db-Signature`	`v1=` followed by the hex HMAC-SHA256 of `{timestamp}.{raw body}`

Use the secret exactly as returned (whsec_…). Use its UTF-8 bytes as the HMAC key. Do not decode it.
Hash the raw body bytes as received. Do not parse and re-serialise the JSON first.
Reject timestamps more than 300 seconds from your server’s clock.
Compare signatures in constant time.

Node.js

Use the SDK helper:

import { verifyWebhookSignature } from '60db-service';

const ok = verifyWebhookSignature({
  rawBody,                                          // the exact bytes received
  signature: req.headers['x-60db-signature'],
  timestamp: req.headers['x-60db-timestamp'],
  secret: process.env.SIXTYDB_WEBHOOK_SECRET,       // whsec_…
});

Or with Node’s crypto module:

import crypto from 'node:crypto';

function verifyRaw(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp || '') || !/^v1=[a-f0-9]{64}$/.test(signature || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(timestamp).update('.').update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Python

Use the SDK helper:

from sixtydb import verify_webhook_signature

ok = verify_webhook_signature(raw_body, request.headers.get("X-60db-Signature"),
                              request.headers.get("X-60db-Timestamp"), secret)

Or with the standard library:

import hashlib
import hmac
import time

def verify_raw(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if not (timestamp or "").isdigit() or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body,
                                hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

Test with curl

curl cannot verify a signature, but you can send a signed test request to your endpoint:

TS=$(date +%s)
BODY='{"type":"call.completed","data":{"id":"test"}}'
SECRET='whsec_your_secret'
SIG="v1=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')"

curl -X POST https://your-server.example.com/webhooks/60db \
  -H "Content-Type: application/json" \
  -H "X-60db-Event: call.completed" \
  -H "X-60db-Event-Id: test-1" \
  -H "X-60db-Timestamp: $TS" \
  -H "X-60db-Signature: $SIG" \
  -d "$BODY"

Rotate the secret

curl -X POST https://api.60db.ai/agents/AGENT_ID/rotate-webhook-secret \
  -H "Authorization: Bearer $SIXTYDB_API_KEY"

The response includes a new webhook_secret. The old secret stops working at once. This covers tool calls and events, including retries that have not been sent yet. Update your server with the new secret right after you rotate. Until you do, signatures will not verify. To limit the gap, store the new value and redeploy in one step.

Agents: setup, call lifecycle, pricing and limits
Get call and Get transcript
List tool events
Rotate webhook secret

Get Started

SDKs

Core Features

Agent Tools and Webhooks

Overview

Define tools

Tool call request

Your reply

Example tool endpoint (Node.js)

Example tool endpoint (Python)

Call transfer

Events

Envelope

Event headers

Retries

Verify signatures

Node.js

Python

Test with curl

Rotate the secret

​Overview

​Define tools

​Tool call request

​Your reply

​Example tool endpoint (Node.js)

​Example tool endpoint (Python)

​Call transfer

​Events

​Envelope

​Event headers

​Retries

​Verify signatures

​Node.js

​Python

​Test with curl

​Rotate the secret

​Related

Overview

Define tools

Tool call request

Your reply

Example tool endpoint (Node.js)

Example tool endpoint (Python)

Call transfer

Events

Envelope

Event headers

Retries

Verify signatures

Node.js

Python

Test with curl

Rotate the secret

Related