Call transfer by webhook

When a caller asks to speak to a person, an agent with call transfer turned on hands the call over. A static transfer always goes to the same number. A webhook transfer asks your system first: Pineyard calls an HTTPS endpoint you run, sends it the details of the call, and transfers to whatever number you send back. You can use this to route by who is on shift, which branch the caller belongs to, the campaign, or the contact’s account owner.

Webhook transfer may not be available for your workspace yet. If it isn’t, the dashboard doesn’t show the Webhook option, and the API refuses transferMode: "WEBHOOK" with 400 transfer_webhook_unavailable. Contact Pineyard to enable it.

How it works

During a call, the caller asks for a human.
While the caller is on hold, Pineyard sends a signed POST to your URL with details of the call and contact, and the reason for the transfer.
Your endpoint replies 2xx with {"to_number": "+919876543210"} before the timeout runs out.
Pineyard transfers the call to that number.

If your endpoint doesn’t send back a usable number in time, the call goes to the agent’s fallback number. If the agent has no fallback number, the AI apologises and the conversation continues. There are no retries, because the caller is on hold while Pineyard waits.

Turn it on for an agent

In the dashboard

Open the agent, go to Call transfer, turn transfer on and choose Webhook. Then set:

Webhook URL: your endpoint.
Signing secret (optional, recommended): Pineyard uses it to sign every request. You can set, replace or remove it, but once saved it is never shown again.
Timeout: how long Pineyard waits for your answer.
Fallback number (optional): used when your endpoint has no answer. In webhook mode, this replaces the static transfer number.

With the API

The same settings are fields on POST /agents and PATCH /agents/{id} (scope agents.edit):

Field	Meaning
`transferEnabled`	`true` to let the agent transfer calls.
`transferMode`	`STATIC` (default) transfers to `transferNumber`. `WEBHOOK` asks `transferWebhookUrl` for a number on every transfer.
`transferWebhookUrl`	Your endpoint. `https://`, port 443, no credentials in the URL, up to 2048 characters. `null` removes it.
`transferWebhookSecret`	Write-only signing secret, up to 1024 characters. A string sets it, `null` or `""` removes it, and leaving it out keeps the current secret.
`transferWebhookTimeoutMs`	How long Pineyard waits for your answer, from `500` to `4000` milliseconds. Default `3000`.
`transferNumber`	In `WEBHOOK` mode, the optional fallback number (E.164). In `STATIC` mode, the transfer number.

curl -X PATCH https://api.pineyard.ai/agents/$AGENT_ID \
  -H "Authorization: Bearer $PINEYARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transferEnabled": true,
    "transferMode": "WEBHOOK",
    "transferWebhookUrl": "https://example.com/pineyard/transfer",
    "transferWebhookSecret": "a-long-random-string-you-keep-private",
    "transferWebhookTimeoutMs": 3000,
    "transferNumber": "+919800000000"
  }'

Agent responses include transferMode, transferWebhookUrl, transferWebhookTimeoutMs and hasTransferWebhookSecret. The secret itself is never returned.

Only a person signed in to the dashboard can set the URL and secret. A request made with an API key that sets or changes transferWebhookUrl or transferWebhookSecret is refused with 403 transfer_webhook_requires_user. Your URL receives caller and contact details during live calls, so a person must choose it. API keys can still read these fields and switch transferMode between STATIC and WEBHOOK. Sending back the URL the agent already has doesn’t count as a change.

Validation errors:

Status	`error`	Cause
400	`transfer_webhook_url_required`	Transfer is on in `WEBHOOK` mode, but the agent has no `transferWebhookUrl`.
400	`invalid_transfer_webhook_url`	The URL isn’t `https://` on port 443, contains credentials, or is too long. `reason` says which.
400	`invalid_transfer_webhook_secret`	The secret is only whitespace, or longer than 1024 characters.
400	`transfer_webhook_unavailable`	Webhook transfer isn’t enabled for your workspace.
403	`transfer_webhook_requires_user`	An API key tried to set or change the URL or secret.

Duplicating an agent copies its transfer settings, including the URL and the secret.

The request

POST /pineyard/transfer HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Pineyard-Transfer/1
X-Pineyard-Event: call.transfer.resolve
X-Pineyard-Timestamp: 1792137600000
X-Pineyard-Signature: v1=5d0c6f2b8e0a4f6c9b3e1d7a2c4f8e6b0a9d3c5e7f1b2a4c6e8d0f2a4b6c8e0d

{
  "event": "call.transfer.resolve",
  "version": "2026-10-16",
  "call_id": "00000000-0000-4000-8000-0000000000b1",
  "agent_id": "00000000-0000-4000-8000-0000000000a7",
  "workspace_id": "00000000-0000-4000-8000-0000000000f1",
  "direction": "outbound",
  "from_number": "+918000000000",
  "to_number": "+919812345678",
  "campaign_id": "00000000-0000-4000-8000-0000000000c1",
  "contact": {
    "id": "00000000-0000-4000-8000-0000000000d1",
    "name": "Jordan Example",
    "phone": "+919812345678"
  },
  "reason": "Caller wants to discuss a refund with a person"
}

Header	Value
`X-Pineyard-Event`	Always `call.transfer.resolve`.
`X-Pineyard-Timestamp`	When the request was sent, as Unix time in milliseconds.
`X-Pineyard-Signature`	`v1=<hex>`, sent only if the agent has a signing secret. See Verify the signature.
`User-Agent`	`Pineyard-Transfer/1`

Field	Meaning
`event`	`call.transfer.resolve`.
`version`	Payload version, currently `2026-10-16`. Fields may be added in the same version, so ignore any field you don’t recognise.
`call_id`	The Pineyard call ID, usable with `GET /calls/{id}`. Can be `null`, for example on an inbound call Pineyard hasn’t recorded yet.
`agent_id`, `workspace_id`	The agent taking the call and its workspace.
`direction`	`inbound`, `outbound`, or `null` if unknown.
`from_number`, `to_number`	The call’s caller and called numbers, normalised to E.164, or `null` if unknown. On an outbound call `to_number` is the person being called. On an inbound call `from_number` is the caller.
`campaign_id`	The campaign the call belongs to, or `null`.
`contact`	`{ id, name, phone }` of the Pineyard contact on the call, or `null`. `name` can be `null`, and is cut to 200 characters.
`reason`	A short, plain-language reason for the transfer, written by the agent, up to 500 characters. Can be `null`.

The response

Reply with any 2xx status and a JSON body containing the number to transfer to:

{ "to_number": "+919876543210" }

to_number must be one number in E.164 format with a leading +. Pineyard doesn’t guess a country code. Don’t send a list or alternatives (such as "+919876543210, +919876543211" or "+91... or +91...").
The answer must arrive within the agent’s transferWebhookTimeoutMs. That budget also covers connecting to your server and Pineyard’s own processing of the call, so answer well inside it. Keep the response body small (under 16 KB).
Redirects aren’t followed.

Pineyard treats any of these as no one available:

a non-2xx status, a redirect, a timeout or a connection error
a body that isn’t JSON, or one with no to_number, a null or empty to_number, or a to_number that isn’t a valid number with a +
a to_number that contains more than one number, for example separated by ,, /, ;, |, or or and
a to_number that is one of the two parties already on the call (the caller or the called number)

In those cases the call goes to the agent’s fallback transferNumber if one is set. Otherwise the AI tells the caller no one is available and keeps helping them. Pineyard never retries a transfer request. If your workspace is suspended, Pineyard doesn’t call your endpoint at all. Transfers go straight to the fallback number, as if no one were available. To deliberately send a caller to the fallback number (for example, outside office hours), reply 200 {"to_number": null} or any non-2xx status.

Verify the signature

When the agent has a signing secret, X-Pineyard-Signature is v1= followed by the lowercase hex HMAC-SHA256, keyed with your secret, of:

{X-Pineyard-Timestamp}.{raw request body}

Compute it over the raw bytes of the body, before parsing the JSON. Compare in constant time, and reject requests whose timestamp is more than 5 minutes from your clock, to block replays. The timestamp is in milliseconds.

import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET = process.env.PINEYARD_TRANSFER_SECRET
const TOLERANCE_MS = 5 * 60 * 1000
const app = express()

app.post('/pineyard/transfer', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Pineyard-Timestamp') ?? ''
  const signature = (req.get('X-Pineyard-Signature') ?? '').replace(/^v1=/, '')

  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() - Number(timestamp)) > TOLERANCE_MS) {
    return res.status(401).end()
  }

  const expected = createHmac('sha256', SECRET)
    .update(`${timestamp}.`)
    .update(req.body) // raw Buffer
    .digest('hex')
  const ok = signature.length === expected.length
    && timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!ok) return res.status(401).end()

  const event = JSON.parse(req.body.toString('utf8'))
  const toNumber = pickAgentFor(event) // your routing: on-shift rota, account owner, branch...

  // Answer fast: the caller is on hold. null sends the call to the fallback number.
  res.json({ to_number: toNumber ?? null })
})

import hashlib, hmac, os, time
from flask import Flask, request, abort, jsonify

SECRET = os.environ["PINEYARD_TRANSFER_SECRET"].encode()
TOLERANCE_MS = 5 * 60 * 1000
app = Flask(__name__)

@app.post("/pineyard/transfer")
def pineyard_transfer():
    timestamp = request.headers.get("X-Pineyard-Timestamp", "")
    signature = request.headers.get("X-Pineyard-Signature", "").removeprefix("v1=")

    if not timestamp.isdigit() or abs(time.time() * 1000 - int(timestamp)) > TOLERANCE_MS:
        abort(401)

    raw = request.get_data()  # raw bytes, before JSON parsing
    expected = hmac.new(SECRET, timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.get_json()
    to_number = pick_agent_for(event)  # your routing: on-shift rota, account owner, branch...

    # Answer fast: the caller is on hold. None sends the call to the fallback number.
    return jsonify(to_number=to_number)

If you don’t set a secret, requests aren’t signed and X-Pineyard-Signature isn’t sent. Set a secret for anything beyond a quick test.

Requirements

The URL must be https:// on port 443, with no username or password in it.
It must be reachable from the public internet. Pineyard won’t connect to private, loopback or link-local addresses, including through DNS. A URL that resolves to one of these is treated as no one available.
Your endpoint must answer well within the timeout (500 to 4000 ms, 3000 ms by default), which also covers connecting and Pineyard’s own processing. Look up your routing data ahead of time or keep it cached, and don’t call slow services before replying.

Testing

Set a fallback number before going live, so a slow or failing endpoint still reaches a person.
Use a test call or a web session from the dashboard, and ask the agent to speak to a person.
Log the raw body and headers of the first few requests, and check that your signature check accepts them before you start rejecting unsigned or invalid requests.
To test the fallback, temporarily return 503 or {"to_number": null}: the call should go to the fallback number, or, without one, the agent should apologise and carry on.
A tunnelling tool that gives you a public https:// URL works for local development. Make sure it answers well within the timeout.

Get started

Concepts

Guides

Call transfer by webhook

How it works

Turn it on for an agent

In the dashboard

With the API

The request

The response

Verify the signature

Requirements

Testing

​How it works

​Turn it on for an agent

​In the dashboard

​With the API

​The request

​The response

​Verify the signature

​Requirements

​Testing

How it works

Turn it on for an agent

In the dashboard

With the API

The request

The response

Verify the signature

Requirements

Testing