Callback Configuration

Last Updated: Friday, January 10, 2020

Overview

A callback entity is a registration to receive callback events to an external URL. It is identified by a CallbackID, which uniquely identifies the record. Additionally, each callback is unique for a given event type and active date range.

Topics in this Section

Callback Entity

The following is the JSON representation of a callback entity within the APIs.

{
   "callback_id":"Hzh39LP3",
   "event_type":"person_added",
   "destination":{
      "url":"http://destination.url",
      "method":"POST",
      "content_type":"application/json"
   },
   "start_date":"2017-01-01T00:00Z",
   "end_date":"2017-02-01T00:00Z",
   "url":"/companies/:company_key/mobiledb/config/callbacks/:callback_id",
   "created_at":"2017-04-15T14:30Z",
   "updated_at":"2017-05-18T19:30Z"
}

Elements

Data Element	Type	Description	Required	Default
callback_id	String	Vibes unique identifier for each callback record.	N/A
event_type	String	Event type to trigger this callback.	Required
destination.url	String	External URL to submit the callback data.	Required
destination.method	String	Method to submit the data to the destination URL. POST and PUT are valid methods.	Optional	POST
destination.content_type	String	Content type to set when submitting the data to the destination URL. Valid content types: `application/json` `text/json`	Optional	`application/json`
start_date	Timestamp	Date this callback starts. It should be in the ISO 8601 format - for example: 2017-04-05T14:30Z.	Optional	Now
end_date	Timestamp	Date this callback ends. It should be in the ISO 8601 format - for example: 2017-04-05T14:30Z.	Optional	No end date
url	String	Unique resource URL for the callback.	N/A
created_at	Timestamp	Date this callback was created. It will be in the ISO 8601 format - for example: 2017-04-05T14:30Z.	N/A
updated_at	Timestamp	Date this callback was last updated. It will be in the ISO 8601 format - for example: 2017-04-05T14:30Z.	N/A
list_id	String	Vibes unique identifier for a Subscription List.	Required for Subscription Event Types
campaign_id	String	Vibes unique identifier for an Acquisition Campaign.	Required for Acquisition Event Types
source_code	String	The short code, long code or alpha code you want to receive unmatched message events for.	Required for Unmatched Message Event Types
country_code	String	The country code for the source code you want to receive unmatched message events for.	Required for Unmatched Message Event Types
campaign_token	String	The campaign token for the wallet campaign.	Required for Wallet Item Event Types

Person Event Types

The person_added callback event is triggered when a new Person record is added into the Mobile Database.

To register an endpoint to receive the person_added callback, follow this example

{
  "event_type":"person_added",
  "destination":{
     "url":"https://YOUR.DESTINATION.URL",
     "method":"POST",
     "content_type":"application/json"
  }
}

The person_updated callback event is triggered when an existing Person record has been modified in the Mobile Database.

To register an endpoint to receive the person_updated callback, follow this example

{
  "event_type":"person_updated",
  "destination":{
     "url":"https://YOUR.DESTINATION.URL",
     "method":"POST",
     "content_type":"application/json"
  }
}

Subscription Event Types

The subscription_added callback event is triggered when a Person has been added to a Subscription List.

The subscription_removed callback event is triggered when a Person has been removed from a Subscription List.

To register an endpoint to receive the subscription_added callback, follow this example:

{
   "event_type":"subscription_added",
   "subscription_added":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"https://YOUR.DESTINATION.URL",
     "method":"POST",
     "content_type":"application/json"
  }
}

To register an endpoint to receive the subscription_removed callback, follow this example:

{
   "event_type":"subscription_added",
   "subscription_added":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"https://YOUR.DESTINATION.URL",
     "method":"POST",
     "content_type":"application/json"
  }
}

More information on Subscription Callbacks is available here.

Acquisition Campaign Event Types

The ack_participant_added callback event is triggered when a new Participant has been added to the Acquisition Campaign.

The ack_participant_changed callback event is triggered when a Participant has confirmed or declined the opt-in.

{
  ...
  "event_type": "ack_participant_added",
  "ack_participant_added": {
    "campaign_id": "c1234"
  },
  ...
}

{
  ...
  "event_type": "ack_participant_changed",
  "ack_participant_changed": {
    "campaign_id": "c1234"
  },
  ...
}

Subscription List Event Types

The subscription_list_added callback event is triggered when a new Subscription List has been created in the Mobile Database.

The subscription_list_updated callback event is triggered whenever a Subscription List has been modified in the Mobile Database.

Unmatched Message Event Types

The unmatched_message_received callback event is triggered when a message originating from a consumer does not match any campaign or system keyword.

{
  ...
    "event_type": "unmatched_message_received",
    "unmatched_message_received": {
        "source_code": "52623",
        "country_code": "1"
    },
  ...
}

Wallet Event Types

The wallet_item_install callback event is triggered when a new wallet item is installed by an end user.

The wallet_item_remove callback event is triggered when a wallet item is removed by an end user.

{
  ...
  "event_type": "wallet_item_install",
  "wallet_item_install": {
    "campaign_token": "Xdc12d34"
  },
  ...
}

{
  ...
  "event_type": "wallet_item_remove",
  "wallet_item_remove": {
    "campaign_token": "Xdc12d34"
  },
  ...
}

Push Device Event Types

The device_added callback event is triggered when a new app has been installed on a device or when a device is moved from another person to this person.

The device_removed callback event is triggered when an app has been uninstalled from a device, otherwise no longer available, or when a device is moved from this person to another person.

The device_updated callback event is triggered when an Apple or Google push_token is added or removed. It will not be triggered for other types of updates.

{
  ...
  "event_type": "device_added",
  "device_added": {
    "app_id": "9aab65b3-a543-4d51-b7d6-32314747f316"
  },
  ...
}

{
  ...
  "event_type": "device_removed",
  "device_removed": {
    "app_id": "9aab65b3-a543-4d51-b7d6-32314747f316"
  },
  ...
}

{
  ...
  "event_type": "device_updated",
  "device_updated": {
    "app_id": "9aab65b3-a543-4d51-b7d6-32314747f316"
  },
  ...
}