Advanced webhooks

A simple webhook posts the whole payload as JSON. When the receiving system expects something else, such as a specific JSON shape, form fields, an API token header, or a PUT to a record URL, use a custom (advanced) webhook. You control the request and fill it with values from the call.

Two ways to build a custom request

	Create Custom Webhook	Advanced mode
Where	Agent workflow → Webhook stage → Add Webhook → Create Custom Webhook	Agent Webhooks settings → set Mode to Advanced
Methods	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
Body types	None, Form Data, JSON, Raw	Text template
Import from cURL	Yes	No
Signed (`X-Signature`)	Yes: HMAC-SHA256 by default, or RSA-SHA256	No. Add your own secret header.
Recommended for	New webhooks	Existing setups and API-created webhooks

Both fire on the events you select, like simple webhooks.

Create a custom webhook

Open the webhook picker

In your agent’s workflow, open the Webhook stage and click to add a webhook. The Add Webhook window lists App Center integrations you can use as webhooks. Click Create Custom Webhook in the top-right corner.

Add Webhook window listing App Center integrations, with the Create Custom Webhook button in the top-right corner highlighted — Create Custom Webhook in the Add Webhook window

Set the method, URL, headers, and query parameters

Choose the Method and enter the URL. Add Headers (for example, Authorization for the receiving API) and Query params as key-value pairs.

HTTP (Send HTTP request) editor with Method and URL fields, an Authorization header, and a query parameter — Method, URL, headers, and query parameters

Build the body

Choose a Body Type: None, Form Data, JSON, or Raw. Then write the body and insert call values from the variable picker, such as the contact’s name, the call outcome, a key question’s answer, or a contact data field.

Body Type dropdown open with None, Form Data, JSON, and Raw options — Body types

Variable picker open over the Raw Body field, listing Id, Session id, Contact, Duration, Status, and other call variables — Inserting call variables into the body

Answers to your key questions are available as variables too.

Choose how to sign the request

Requests are signed with HMAC-SHA256 using your account’s secret. Turn on Sign with RSA-SHA256 to sign with the Callers private key instead. See Validating webhook signatures.

Send a test request

Click Send Test Request. The response status and body from your endpoint appear on the right.

Response panel after a test request, showing success true, status 201, and the response headers — Test response

Choose events and save

Back on the workflow, choose which events send this webhook. For example, send it only when the contact is interested.

Post-Call Actions panel with the Perform action for dropdown open, listing outcomes such as Voice mail, Interested, and Not interested — Choosing the call outcomes that send the webhook

Import a cURL command

If the receiving API documents its requests as cURL commands, click Import next to cURL, paste the command, and click Import again. The method, URL, headers, query parameters, and body are filled in for you.

Import cURL dialog with a pasted curl POST command and an Import button — Importing a cURL command

HTTP request editor with Method POST, the URL, Content-Type and Authorization headers, and a query parameter filled in from the cURL command — Request fields filled from the cURL command

Advanced mode on an agent webhook

In the agent’s Webhooks settings, switch a webhook’s Mode to Advanced to open the Advanced Webhook editor. Set the method and URL, use the Headers, Query Parameters, and Body tabs, insert variables, and click Test Request to check the response. Requests from advanced mode aren’t signed. Protect your endpoint with a secret you add yourself, such as an Authorization header or a token query parameter, and allow only the Callers IP addresses.

Template syntax

In the dashboard you insert values with the variable picker. Underneath, and when you create advanced webhooks through the API, a placeholder is the path to a payload field wrapped in double angle brackets: <<path>>.

Placeholder	Resolves to
`<<id>>`	Call ID
`<<webhookEvent>>`	Event that triggered the delivery
`<<contact.name>>`	Contact name
`<<contact.phoneNumber>>`	Contact phone number
`<<contact.data.crm_id>>`	A field from the contact’s uploaded data
`<<successCriteria.name>>`	Matched success criterion
`<<summary.Budget approved>>`	The answer to the key question “Budget approved”
`<<transcript>>`	The whole transcript (array)

Paths use the field names from the payload reference, with dots for nesting and [0] for array items. How values are inserted:

In a JSON body, a placeholder that is the entire string value ("answer": "<<summary.Budget approved>>") is replaced with the value itself, keeping its type: booleans, numbers, objects, and arrays stay as JSON, not strings.
A placeholder inside longer text ("note": "Call with <<contact.name>>") is converted to text.
Values that don’t exist resolve to null.

Example body for a CRM update:

{
  "external_id": "<<contact.data.crm_id>>",
  "callers_call_id": "<<id>>",
  "outcome": "<<successCriteria.name>>",
  "goal_reached": "<<successCriteria.goalReached>>",
  "budget_approved": "<<summary.Budget approved>>",
  "note": "AI call with <<contact.name>> ended: <<status>>"
}

Advanced webhooks through the API

Set isAdvanced: true and describe the request in advancedWebhook when you subscribe a webhook or create, replace, or patch an agent:

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/webhook/subscribe" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM update",
    "url": "https://crm.example.com/api/calls",
    "events": ["POST_PROCESSING_FINISHED:INTERESTED"],
    "isAdvanced": true,
    "advancedWebhook": {
      "url": "https://crm.example.com/api/calls",
      "method": "POST",
      "headers": [{ "name": "Authorization", "value": "Bearer YOUR_CRM_TOKEN" }],
      "parameters": [{ "name": "source", "value": "callers" }],
      "body": "{\"external_id\": \"<<contact.data.crm_id>>\", \"outcome\": \"<<successCriteria.name>>\"}"
    }
  }'

const body = {
  external_id: "<<contact.data.crm_id>>",
  outcome: "<<successCriteria.name>>",
};

await fetch(`https://api.callers.ai/agents/${agentId}/webhook/subscribe`, {
  method: "POST",
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "CRM update",
    url: "https://crm.example.com/api/calls",
    events: ["POST_PROCESSING_FINISHED:INTERESTED"],
    isAdvanced: true,
    advancedWebhook: {
      url: "https://crm.example.com/api/calls",
      method: "POST",
      headers: [{ name: "Authorization", value: `Bearer ${process.env.CRM_TOKEN}` }],
      parameters: [{ name: "source", value: "callers" }],
      body: JSON.stringify(body), // the template is a string
    },
  }),
});

import json

template = {"external_id": "<<contact.data.crm_id>>", "outcome": "<<successCriteria.name>>"}

requests.post(
    f"https://api.callers.ai/agents/{agent_id}/webhook/subscribe",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "CRM update",
        "url": "https://crm.example.com/api/calls",
        "events": ["POST_PROCESSING_FINISHED:INTERESTED"],
        "isAdvanced": True,
        "advancedWebhook": {
            "url": "https://crm.example.com/api/calls",
            "method": "POST",
            "headers": [{"name": "Authorization", "value": f"Bearer {os.environ['CRM_TOKEN']}"}],
            "parameters": [{"name": "source", "value": "callers"}],
            "body": json.dumps(template),  # the template is a string
        },
    },
)

advancedWebhook.url must be HTTPS. The top-level url is still required and identifies the webhook (subscribing the same url again merges events). Webhooks created this way work like advanced mode and aren’t signed.

Troubleshooting

A placeholder arrives as null

The path doesn’t match a payload field, or the value doesn’t exist for that call (for example, a key question that wasn’t answered). Check spelling and case against the payload reference, and remember that HANG_UP fires before analysis, so summary and successCriteria are empty then.

The receiving API rejects the body

Use Send Test Request to see its response. Check the Body Type matches what the API expects (JSON vs form data) and that you added any required headers, such as Content-Type or an API token.

Signature doesn't verify

Custom webhooks sign the body after placeholders are filled in, with HMAC by default. Verify with your account’s HMAC secret, not the Callers public key, unless you turned on Sign with RSA-SHA256.

Webhook payload

Every field you can use in templates.

Validating signatures

Verify HMAC and RSA signatures.

Webhooks overview

Events, delivery, retries, and logs.

App Center

Ready-made integrations you can run as webhooks.

Get started

Guides

Webhooks

Endpoints

Advanced webhooks

Two ways to build a custom request

Create a custom webhook

Import a cURL command

Advanced mode on an agent webhook

Template syntax

Advanced webhooks through the API

Troubleshooting

Webhook payload

Validating signatures

Webhooks overview

App Center

​Two ways to build a custom request

​Create a custom webhook

​Import a cURL command

​Advanced mode on an agent webhook

​Template syntax

​Advanced webhooks through the API

​Troubleshooting

​Related

Webhook payload

Validating signatures

Webhooks overview

App Center

Two ways to build a custom request

Create a custom webhook

Import a cURL command

Advanced mode on an agent webhook

Template syntax

Advanced webhooks through the API

Troubleshooting

Related