Webhooks

Understand webhook timing and expected payloads.

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.

Note: Additional Beta webhooks are available in the Notifications section of the Connections page.

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


Parameter	Description	Data Type
data	This 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
event	Describes the event for which this payload was sent. In this case, the expected value is Registered Callback	string
time	The UTC time at which the event was created	string
webhookName	The name of the webhook configured in the Mindful UI	string
id	A universally unique identifier (UUID) for the webhook event	string

Registration call object properties

The following table lists the properties of the call object:


Parameter	Description	Data Type	Possible values
ani	For calls in the voice channels, the ANI of the inbound call to Mindful	string 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 registrationThe casing of metadata items will be maintained as it was received by Mindful (for example, "X-Transfer" vs. "X-transfer").	object
phoneNumber	For callbacks, this is the number for which the callback was registered.	string
registrationDuration	The duration, in seconds, that a customer spent registering their callback via the voice channel	number or null
scheduledFor	For scheduled callbacks, this is the time at which the callback is scheduled to be dialed.	string or null
source	The Phone Number or Widget that was used to register this Callback	string or null
sourceType	This 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


Parameter	Description	Data Type
data	This 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
event	Describes the event for which this payload was sent. In this case, the expected value is Finalized Callback.	string
time	The UTC time at which the event was created	string
webhookName	The name of the webhook configured in the Mindful UI	string
id	A universally unique identifier (UUID) for the webhook event	string

Finalization call object properties

The following table lists the properties of the call object:


Parameter	Description	Data Type	Possible Values
actualCallbackTime	The actual duration, in seconds, that the customer waited for the callback, based on the difference between the createdAt time and the processedAt times	number or null
ani	For calls in the voice channels, the ANI of the inbound call to Mindful	string 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
choseToHold	For inbound calls in the voice channel, this indicates whether the caller chose to hold for an agent.	boolean
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
duplicateCallback	Indicates whether an attempt was made to register a callback to a phone number that Mindful considered a duplicate callback request	boolean
endedAt	An RFC 3339-formatted UTC timestamp representing the time at which the callback attempt ended	string or null
endOfBusinessDay	Indicates whether a call arrived during a time period Mindful considered the end of the business day	boolean
estimatedCallbackTime	The time at which Mindful expects the callback to be dialed	number
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 null
id	The identifier for this call attempt	string
maxEcbtExceeded	Indicates whether ECBT exceeded the configured ECBT Threshold when this call arrived. Not implemented for digital callbacks.	boolean
maxScheduledCallsExceeded	Indicates whether the Maximum Callbacks Allowed per Schedule Interval was exceeded for the requested timeslot.	boolean
maxTollRateExceeded	Indicates whether an attempt was made to register a callback to a phone number whose per-minute toll charges exceed the maximum rate permitted.	boolean
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
nextDayCallbackOffered	For 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
nextDayCallbackScheduled	For calls which were offered a next-business-day callback, this indicates whether that option was accepted.	boolean
originalId	The original dispatch ID associated with the callback request. For retries or rescheduled callbacks, this is the ID of the original call.	string
outcome	Indicates the final result of the callback	string	Success Failure Canceled Unavailable Chose Hold Chose Messaging Text Scheduling Abandoned Not Completed Unknown
outsideHours	Indicates 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
phoneNumber	E.164-formatted phone number	number
processedAt	An 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
punctuality	The time, in seconds, between the estimatedFor and processedAt timestamps. Positive numbers indicate late callbacks and negative numbers indicate early callbacks.	number or null
registrationDuration	The duration, in seconds, that a customer spent registering their callback via the voice channel	number or null
segmentName	The name of the Segment that processed this call. If null, the call was not processed by a segment.	string or null
source	The Phone Number or Widget that was used to register this callback	string
sourceType	This 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
wasPunctual	For 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