Skip to main content

​
Adding a Webhook to Your Campaign

To add a webhook to your campaign, navigate to your campaign settings → Workflow tab → Post-Call Actions → Add.
webhook workflow tab
In the opened window, you can select the action that will be executed after a call. We offer a wide range of integrations that can be used, but for this guide, we’ll focus on the Create Custom Webhook button in the upper-right corner.
add webhook

​
Configure an Advanced Webhook

In the webhook editor, you can flexibly configure your HTTP request. First, you need to enter the URL where you will send the request and select the HTTP Method (GET, POST, PUT, PATCH, or DELETE). Then configure Headers for authorization (if needed) and add Query Parameters (if needed) that will be prepended to the URL.
webhook headers and parameters
Next, you can configure the Request Body. First, select one of the available formats: Form Data, JSON, or Raw.
webhook body formats
After selecting the format, you need to write the request body itself. Here you can use the standard variables we provide as values, and custom variables configured through Key Questions will also be available. (Learn more about Key Questions here).
webhook variables

​
Import cURL Configuration

In addition to manual configuration, you can set up the entire request by importing a cURL command.
webhook cURL import
To do this, find the Import button in the upper-right corner, and in the opened window, paste your cURL command and click the Import button again.
webhook cURL example
All necessary values will automatically populate in the method, URL, headers, parameters, and body.
webhook cURL imported

​
Testing Your Webhook

After configuring the request, you can test it by clicking the Send Test Request button in the upper-right corner. In the space on the right below this button, you’ll see a detailed response with the status code and body.
webhook response

​
Configuring Webhook Triggers

Finally, you need to define when the webhook will be sent. You can configure the webhook to trigger based on specific call statuses (for example, send the webhook only to interested leads).
webhook statuses

​
Webhook payload example

Use the example below as a template when mapping fields inside downstream systems:
webhook.json
{
  "callStatus": "COMPLETED",
  "createdAt": "2024-03-11T14:56:41.642Z",
  "phoneFrom": "+15555551234",
  "phoneTo": "+15555554321",
  "status": "INTERESTED",
  "postProcessStatus": "INTERESTED",
  "hangUpReason": "CALL_FINISHED",
  "duration": 128,
  "totalDuration": 150,
  "isIncoming": false,
  "contactStatus": {
    "callMeLater": false,
    "doNotCall": false,
    "wrongNumber": false
  },
  "conversationFlow": [],
  "summary": {
    "Inquiry Asked": {
      "description": "Interested in learning more about our services",
      "options": [],
      "order": 1,
      "type": "YES_NO",
      "value": false
    }
  },
  "campaign": {
    "id": "{campaignId}",
    "name": "{campaignName}"
  },
  "id": "{callId}",
  "contact": {
    "id": "{contactId}",
    "name": "John",
    "phoneNumber": "+1234567890",
    "data": {
      "email": "[email protected]",
      "position": "Product Manager",
      "company": "Callers"
    }
  },
  "twilio": {
    "accountSid": "{accountSid}",
    "callSessionId": "{callSessionId}"
  },
  "organizationId": "{organizationId}",
  "account": {
    "id": "{organizationId}",
    "name": "{organizationName}"
  },
  "transcript": [
    {
      "content": "Hello, this is Callers. How can I assist you today?",
      "role": "Assistant"
    },
    {
      "content": "Hi, can you tell me more about your services?",
      "role": "user"
    },
    {
      "content": "Certainly! We offer personalized AI calling services. Would you like to schedule a demo?",
      "role": "Assistant"
    },
    {
      "content": "Yes, that sounds great. Thank you!",
      "role": "user"
    },
    {
      "content": "You're welcome! I'll set that up and send you a confirmation. Have a great day!",
      "role": "Assistant"
    }
  ],
  "interested": {
    "description": "The caller showed interest in scheduling a demo, indicating a positive engagement.",
    "reached": true
  },
  "successCriteria": {
    "goalReached": true,
    "description": "Customer agreed to schedule a demo",
    "name": "Demo Scheduled",
    "reason": "Positive response to scheduling request",
    "type": "INTERESTED"
  },
  "events": [
    {
      "type": "SMS",
      "data": {
        "sent": true,
        "status": "queued",
        "sentAt": "2024-11-28T22:37:01.000Z",
        "sentTo": "+1999999999",
        "uri": "{uri}",
        "smsSid": "{smsSid}",
        "sentFrom": "+1999999999",
        "text": "{smsTemplateText}"
      }
    },
    {
      "type": "FORWARD",
      "data": {
        "phoneNumber": "+1999999999",
        "contactAsCallerId": true
      }
    }
  ],
  "webhookUrl": "{webhookUrl}",
  "webhookEvent": "CONNECTED",
  "webhookEvents": [
    "HANG_UP",
    "CONNECTED",
    "POST_PROCESSING_FINISHED:NOT_INTERESTED",
    "POST_PROCESSING_FINISHED:CALL_ME_LATER",
    "POST_PROCESSING_FINISHED:INTERESTED",
    "POST_PROCESSING_FINISHED:VOICE_MAIL"
  ],
  "webhookStatuses": [
    "INTERESTED",
    "NOT_INTERESTED",
    "CALL_ME_LATER",
    "WRONG_NUMBER",
    "DO_NOT_CALL",
    "COMPLETED",
    "FAILED",
    "VOICE_MAIL",
    "BUSY",
    "NO_ANSWER"
  ],
  "isTestCall": false,
  "sessionId": "{sessionId}",
  "slackUrl": "{slackUrl}"
}

​
Webhook fields reference

Refer to the table below for every field that can appear in the payload:
FieldDescription
createdAtTimestamp when the call was initiated in ISO 8601 format.
phoneFromPhone number from which the call originated.
status

Composite status of a call. It includes the call status, the reason for call hang up, and the candidate status.

Call progress status:

  • NEW
  • IN_PROGRESS
  • BUSY
  • NO_ANSWER
  • VOICE_MAIL
  • FAILED

Call connection status:

  • USER_REQUESTED_HANGUP
  • ADMIN_MANUAL_HANGUP
  • VOICE_MAIL_DETECTED
  • SILENCE_DETECTED
  • USER_MANUAL_HANGUP
  • CONVERSATION_LLM_TECHNICAL_ISSUES
  • OTHER_TECHNICAL_ISSUES
  • CALL_FINISHED
  • CALL_FORWARDED
  • UNKNOWN
  • SOCKET_DISCONNECTED

Contact response to call:

  • INTERESTED: The contact expressed interest in the purpose of the call.
  • NOT_INTERESTED: The contact is not interested in the purpose of the call.
  • CALL_ME_LATER: The contact requested a follow-up call at a later time.
  • PENDING: The contact has been returned to the call queue for further attempts.
  • WRONG_NUMBER: The number dialed did not correspond to the intended contact.
  • DO_NOT_CALL: The contact requested not to receive future calls.

callStatus

Call status:

  • NEW
  • IN_PROGRESS
  • FAILED
  • COMPLETED: The user answered and the call ended successfully.
  • NO_ANSWER
  • BUSY
  • VOICE_MAIL
  • DO_NOT_CALL_REGISTRY_MATCHED
postProcessStatus

Candidate status for that call:

  • INTERESTED
  • NOT_INTERESTED
  • CALL_ME_LATER
  • WRONG_NUMBER
  • DO_NOT_CALL
events

Details about specific call events:

  • SMS

    • Data regarding origin, destination and content
  • FORWARDED CALL

  • MEETING

    • Data regarding slot booked, date sent and destination email.
webhookUrlURL to which the Webhook data is sent post-call.
webhookEvent

Event related to the webhook trigger:

  • DIALING
  • CONNECTED
  • FAILED
  • COULD_NOT_CONNECT:BUSY
  • COULD_NOT_CONNECT:NO_ANSWER
  • FORWARDED
  • HANG_UP
  • POST_PROCESSING_FINISHED:VOICE_MAIL
  • POST_PROCESSING_FINISHED:INTERESTED
  • POST_PROCESSING_FINISHED:NOT_INTERESTED
  • POST_PROCESSING_FINISHED:WRONG_NUMBER
  • POST_PROCESSING_FINISHED:CALL_ME_LATER
  • POST_PROCESSING_FINISHED:DO_NOT_CALL
  • FORWARDED_CALL_FINISHED
webhookEventsList of selected events for triggering the webhook.
hangUpReason

Reason for the call termination:

  • USER_REQUESTED_HANGUP: User asked to hang up.
  • ADMIN_MANUAL_HANGUP: Call ended by an admin.
  • USER_MANUAL_HANGUP: User manually ended the call.
  • CALL_FINISHED: Call ended after the completion of all interactions.
  • CALL_FORWARDED: Call transferred to a designated phone number.
durationDuration of the call with Callers’ agent in seconds.
totalDurationTotal duration of the call including the forwarded call duration in seconds.
contactStatus

Object indicating the contact’s preferences:

  • callMeLater: Boolean indicating if the contact requested a callback later.
  • doNotCall: Boolean indicating if the contact requested not to be called again.
  • wrongNumber: Boolean indicating if the contact reported this as a wrong number.
summaryObject summarizing the Key Questions made during the call.
campaign

Information about the campaign associated with the call:

  • id: Campaign id.
  • name: Name of the campaign.
idUnique identifier for the call.
contact

Details about the person contacted:

  • id: Contact’s identifier.
  • name: Contact’s name.
  • phoneNumber: Contact’s phone number.
  • data: Contains additional properties that can be used as variables in the script during the call
twilio

Twilio information:

  • accountSid: Unique identifier for the Twilio account.
  • callSessionId: Unique session identifier for the call.
organizationIdUnique identifier for the organization.
transcriptArray of dialogue exchanges during the call, with each entry detailing the content spoken and the role of the speaker.
interested

Object detailing whether the caller expressed interest in the services:

  • description: The Interest Criteria defined by the user for the campaign.
  • reached: Boolean indicating whether the Interest Criteria was reached.
successCriteria

Object detailing the success criteria evaluation for the call:

  • goalReached: Boolean indicating if the success criteria was met (true/false)
  • description: Description of the success criteria used for this call
  • name: The given name for the success criteria
  • reason: The reason for choosing this success criteria
  • type: The group the success criteria belongs to - either INTERESTED or NOT_INTERESTED
isTestCallBoolean indicating if the call was a test call.
slackUrlWebhook Url if the account is integrated with Slack.

​
Network Requirements

Callers sends webhooks from the following IP addresses:
If your systems are behind a firewall, whitelist these IP addresses to ensure webhook delivery:
35.245.204.86
35.221.61.75
These IP addresses are also used for action dispatching when your campaigns trigger custom actions (like API calls to external services).