What are callbacks?

Callbacks are HTTP requests made from Dispatch to your application to alert your application about certain events. Callbacks are made via either GET or POST requests, can contain variable substitution and can have optional credentials.

When Dispatch issues a callback (either by GET or POST) it does not pass any specific data back to your application. Any data you want conveyed to your application will need to be included in the URL path. Variable substitution is supported.

Example

GET https://apps.its.uiowa.edu/exampleapp/student/mailhistory/notification123/${studentId}

Callback events

Callbacks can be setup for the following events in Dispatch:

Message Sent:
This callback is made after all the destinations have been processed for a message. For Twilio SMS and Twilio Voice destination you should also use the "Message Delivery Status Change" callback to learn about successful delivery of Twilio messages.
Message Delivery Problem:
This callback is made when Dispatch has encountered some problem trying to generate or deliver a message. This does not include bounces.
Message Delivery Status Change:
This callback only applies to Twilio messages. Twilio allows us the possibility to know if a message was successfully delivered to the recipient. Twilio will rely to Dispatch updates as the message's delivery status changes. See Twilio's documentation for what the various status are for SMS and Voice messages.

A callback is issued when the status changes. See Callbacks for changes in message delivery status for more information on what information is relayed

Communication Complete:
This callback will be made when a communication has completed all steps and has ended in a COMPLETE status. If you choose POST as the callback method, you will receive a JSON payload containing a reference to the batch of messages that was delivered. You can then call that endpoint with the optional includemembers query parameter set to true to get an array of all the members in the completed batch.
Screenshot of callbacks options

Variable substitution

You can create dynamic URLs for your callbacks by printing the variables available from your messages. The following variables are available:

Variable(s) Description Applies to:
Member attributes All of the attributes that are included for each member in the population.
  • Message Sent
  • Message Delivery Problem
  • Message Delivery Status Change
Campaign Environment Variables Any campaign environment suitable for the campaign mode. All
batchId Dispatch's internal ID of the batch of messages sent. All
communicationId Dispatch's internal ID of the communication. All
id Dispatch's unique internal UUID of the message.
  • Message Sent
  • Message Delivery Problem
  • Message Delivery Status Change
memberId Dispatch's unique internal UUID of the message. This variable is provided if the member attributes happen to already include a id variable.
  • Message Sent
  • Message Delivery Problem
  • Message Delivery Status Change

How callbacks are sent

Callbacks are processed in batches. For instance, when a message is sent the callback request added to the callback queue. Callbacks will time out after 120 seconds. If the callback times out or any HTTP status code other than 200 is returned, the request will be tried again in five minutes. After three attempts the callback will be flagged as failed and the communication that requested the callback will be disabled for safety reasons. Any person on the communication notification list will receive an email alerting them that a callback failed and the communication has been disabled.

Callback result history

History is maintained when callbacks are issued. You can see the results of message callbacks from the individual message properties. For an example see Callback results.

Related topics: