Please ensure Javascript is enabled for purposes of website accessibility
Webhooks
  • 13 Jun 2024
  • 6 Minutes to read
  • Dark
    Light
  • PDF

Webhooks

  • Dark
    Light
  • PDF

Article summary

This guide discusses the timing of Mindful webhook events and the contents of each payload. Here you will find example payloads, definitions of parameters, data types, and possible values, where applicable. 

Before receiving webhook events, you must first configure webhooks in the Mindful UI to select which events you would like to receive. To learn more, see Webhooks.


Callback Registration

The Callback Registration event is triggered when Mindful registers a new callback from any channel (voice, web, etc.).

Example Payload

{
    "data": {
        "call": {
            "ani": 13395559005,
            "callTargetId": "4380",
            "callTargetName": "Billing",
            "createdAt": "2024-04-27T01:56:56.000Z",
            "estimatedCallbackTime": 60,
            "estimatedFor": "2024-04-27T01:58:30.000Z",
            "firstPartyCalled": "agent",
            "id": "126b5e1e7f65da3",
            "metadata": {
                "Diversion": "sip:400@10.10.10.10:5060;reason=unknown",
                "User-to-User": "00F7020;encoding=hex",
            },
            "phoneNumber": "+13395559005",
            "registrationDuration": 34.298,
            "scheduledFor": "2024-04-27T01:57:16.000Z",
            "source": "Phone:8525550917",
            "sourceType": "Phone",
            "type": "asap"
        },
        "clientName": "Acme Widgets",
        "event": "Registered Callback",
        "time": "2023-04-27T01:57:31Z",
        "webhookName": "Example Webhook",
        "id": "37ff2b58-386b-7v35-87be-ba88a433e825"
    }
}

Payload Parameters

ParameterDescriptionData Type 
dataThis top-level object contains all other parameters delivered in the webhook event. Technically, all other items in the payload are properties of this single parameter.string
call
This object contains several properties related to the newly registered callback. See the table below for properties of the call object.
object
clientName
The name of the Mindful Organization to which the webhook belongs
string
eventDescribes the event for which this payload was sent. In this case, the expected value is Registered Callback

string

timeThe UTC time at which the event was createdstring
webhookNameThe name of the webhook configured in the Mindful UIstring
idA universally unique identifier (UUID) for the webhook eventstring

Registration call object properties

The following table lists the properties of the call object:

ParameterDescriptionData TypePossible values
ani
For calls in the voice channels, the ANI of the inbound call to Mindful
number or null

callTargetId
Identifies which Call Target is associated with the callback request
string

callTargetName
The name of the Call Target that processed this call
string

createdAt
For first-attempt callbacks and calls without a callback, this is the RFC 3339-formatted UTC timestamp at which Mindful first became aware of the call. For subsequent attempts and rescheduled callbacks, this is the timestamp at which the retry was created by the previous attempt.
string

estimatedCallbackTime
The time at which Mindful expects the callback to be dialed
number or null

estimatedFor
For callbacks, the RFC 3339-formatted UTC timestamp at which the callback was expected to be processed
string or null

firstPartyCalled
Indicates the callback strategy used for the callback
string or null
  • agent
  • customer
id
The identifier for this call attempt
string

metadata
An object describing metadata submitted with a callback registration
The casing of metadata items will be maintained as it was received by Mindful (for example, "X-Transfer" vs. "X-transfer").
object


phoneNumberFor callbacks, this is the number for which the callback was registered.string
registrationDurationThe duration, in seconds, that a customer spent registering their callback via the voice channelnumber or null
scheduledForFor scheduled callbacks, this is the time at which the callback is scheduled to be dialed.string or null
sourceThe Phone Number or Widget that was used to register this Callbackstring or null
sourceTypeThis indicates whether the callback request came via phone or widget.

string or null

  • CBWidget
  • phone
type
This indicates whether the callback was registered as asap or scheduled.
string
  • asap
  • scheduled

Callback Finalization

The Callback Finalization event is triggered when a callback is finalized with any outcome (success, canceled, etc.).

Example Payload

{
    "data": {
        "call": {
            "actualCallbackTime": 1126,
            "ani": "13391159027",
            "callTargetId": "4444",
            "callTargetName": "Billing",
            "choseToHold": false,
            "createdAt": "2024-08-15T15:01:16.000Z",
            "duplicateCallback": false,
            "endedAt": "2024-08-15T15:20:02.000Z",
            "endOfBusinessDay": false,
            "estimatedCallbackTime": 63210,
            "estimatedFor": "2024-08-16T08:34:47.000Z",
            "firstPartyCalled": "customer",
            "id": "9aa7826bc4d37e5bf5",
            "maxEcbtExceeded": false,
            "maxScheduledCallsExceeded": false,
            "maxTollRateExceeded": false,
            "metadata": {
                "Diversion": "sip:400@10.10.10.10:5060;reason=unknown",
                "User-to-User": "00F7020;encoding=hex",
            },
            "nextDayCallbackOffered": false,
            "nextDayCallbackScheduled": false,
            "originalId": "9aa7826bc4d37e5bf5",
            "outcome": "Unavailable",
            "outsideHours": false,
            "phoneNumber": "+12985035375",
            "processedAt": "2024-08-15T15:20:02.000Z",
            "punctuality": 62083,
            "registrationDuration": 0,
            "segmentName": "Billing_Skill200",
            "source": "CBWidget:625ae84aa30e5b3a7ecb6fd6cd8a0634",
            "sourceType": "CBWidget",
            "type": "asap",
            "wasPunctual": false
        },
        "clientName": "Acme Widgets",
        "event": "Finalized Callback",
        "time": "2024-08-27T01:57:31Z",
        "webhookName": "Billing Webhook",
        "id": "6dd9599c-d399-48d6-89e6-4a6x7ea0d244"
    }
}

Payload Parameters

ParameterDescriptionData Type
dataThis top-level object contains all other parameters delivered in the webhook event. Technically, all other items in the payload are properties of this single parameter.string
call
This object contains several properties related to the finalized callback. See the table below for information on properties of the call object.
object
clientName
The name of the Mindful Organization to which the webhook belongs
string
eventDescribes the event for which this payload was sent. In this case, the expected value is Finalized Callback.string
timeThe UTC time at which the event was createdstring
webhookName
The name of the webhook configured in the Mindful UI
string
idA universally unique identifier (UUID) for the webhook event
string

Finalization call object properties

The following table lists the properties of the call object:

ParameterDescriptionData TypePossible Values
actualCallbackTimeThe actual duration, in seconds, that the customer waited for the callback, based on the difference between the createdAt time and the processedAt timesnumber or null
aniFor calls in the voice channels, the ANI of the inbound call to Mindfulnumber or null
callTargetIdIdentifies which Call Target is associated with the callback requeststring
callTargetNameThe name of the Call Target that processed this callstring
choseToHoldFor inbound calls in the voice channel, this indicates whether the caller chose to hold for an agent.boolean
createdAtFor first-attempt callbacks and calls without a callback, this is the RFC 3339-formatted UTC timestamp at which Mindful first became aware of the call. For subsequent attempts and rescheduled callbacks, this is the timestamp at which the retry was created by the previous attempt.string
duplicateCallbackIndicates whether an attempt was made to register a callback to a phone number that Mindful considered a duplicate callback requestboolean
endedAt
An RFC 3339-formatted UTC timestamp representing the time at which the callback attempt ended
string or null

endOfBusinessDayIndicates whether a call arrived during a time period Mindful considered the end of the business dayboolean
estimatedCallbackTimeThe time at which Mindful expects the callback to be dialednumber
estimatedForFor callbacks, the RFC 3339-formatted UTC timestamp at which the callback was expected to be processedstring or null
firstPartyCalledIndicates the callback strategy used for the callbackstring or null
  • agent
  • customer
  • null
idThe identifier for this call attemptstring
maxEcbtExceededIndicates whether ECBT exceeded the configured ECBT Threshold when this call arrived. Not implemented for digital callbacks.boolean
maxScheduledCallsExceededIndicates whether the Maximum Callbacks Allowed per Schedule Interval was exceeded for the requested timeslot.boolean
maxTollRateExceededIndicates whether an attempt was made to register a callback to a phone number whose per-minute toll charges exceed the maximum rate permitted.boolean
metadataAn object describing metadata submitted with a callback registration. The casing of metadata items will be maintained as it was received by Mindful (for example, "X-Transfer" vs. "X-transfer").object
nextDayCallbackOfferedFor calls arriving to Mindful during the end-of-day period, this indicates whether the option to request a callback during the next business day was offered.boolean
nextDayCallbackScheduledFor calls which were offered a next-business-day callback, this indicates whether that option was accepted.boolean
originalIdThe original dispatch ID associated with the callback request. For retries or rescheduled callbacks, this is the ID of the original call.string
outcomeIndicates the final result of the callbackstring
  • Success
  • Failure
  • Canceled
  • Unavailable
  • Chose Hold
  • Chose Messaging
  • Text Scheduling
  • Abandoned
  • Not Completed
  • Unknown
outsideHoursIndicates whether an attempt to register a callback was made outside of the business hours configured for the Call Target or segment that processed this callback request.boolean
phoneNumberE.164-formatted phone numbernumber
processedAtAn RFC 3339-formatted UTC timestamp representing the time at which the first leg of the callback was launched (to either the customer or contact center).string or null
punctualityThe time, in seconds, between the estimatedFor and processedAt timestamps. Positive numbers indicate late callbacks and negative numbers indicate early callbacks.number or null
registrationDurationThe duration, in seconds, that a customer spent registering their callback via the voice channelnumber or null
segmentNameThe name of the Segment that processed this call. If null, the call was not processed by a segment.string or null
sourceThe Phone Number or Widget that was used to register this callbackstring
sourceTypeThis indicates whether the callback request came via phone or widget.string
  • CBWidget
  • phone
type

For callbacks, this indicates whether the callback was registered as asap or scheduled. For other call types, this is unknown.

string
  • asap
  • scheduled
  • unknown
wasPunctualFor callbacks that were launched within the range quoted within the range calculated at the time of registration, this is true. For callbacks that were launched early or late, this is false.boolean

Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.