These callbacks are triggered in response to changes in data associated with the Subscription API. To receive callbacks, please make sure your endpoint is compatible with our endpoint specifications.

🚧
Before you register...
Set up your endpoint before sending any callback configurations. Do not use a "fake" URL to test the configuration, as this will result in errors.

Available Callbacks

MDN formats in callback events are determined by the API version used when creating and altering the callbacks. If Version 2 is used, MDNs will be represented in the E.164 international format. Otherwise, MDNs will be represented without a country code.

Subscription Added Callback

This callback is triggered when a person has been added to a subscription list.

Callback configuration

When registering for this callback, your request body should look something like the below example.:

{
   "callback_type":"subscription_added",
   "subscription_added":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body contains the metadata about the subscription that was added.

{
   "event_id":"AB234SDFD234",
   "callback_type":"subscription_added",
   "event_type":"subscription_added", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "external_person_id":"ex1234",
         "person_key":"c5235a1-e243-42z7-979c-7f6234kl21b60",
         "url":"/companies/:company_key/mobiledb/persons/ABC123",
         "mobile_phone":{
           "mdn":"+1999999999"
         }
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
      "opt_in_date":"2017-01-15T15:34:52Z",
      "source": {
         "acquisition_campaign":"C123456"
      }
   }
}

Subscription Removed Callback

This callback is triggered whenever a person has been removed from a subscription list.

Callback configuration

When registering for this callback, your request body should look something like the below example.

{
   "callback_type":"subscription_removed",
   "subscription_removed":{
         "list_id":"YOUR_SUBSCRIPTION_LIST_ID"
  },
  "destination":{
     "url":"YOUR_DESTINATION_URL_W_HTTPS", /*Do not use a "fake" URL (such as google.com).*/
     "method":"POST",
     "content_type":"application/json"
  }
}

Callback body

The callback body contains data about the subscription that was removed and an opt_out_reason.

{
   "event_id":"AB234SDFD234",
   "callback_type":"subscription_removed",
   "event_type":"subscription_removed", //deprecated
   "event_date":"2017-03-15T15:42:23Z",
   "subscription":{
      "person":{
         "id":"ABC123",
         "external_id":"ex1234",
         "external_person_id":"ex1234",
         "person_key":"c5235a1-e243-42z7-979c-7f6234kl21b60",
         "url":"/companies/:company_key/mobiledb/persons/ABC123",
         "mobile_phone":{
           "mdn":"+1999999999"
         }
      },
      "subscription_list":{
         "id":"1234",
         "url":"/companies/:company_key/mobiledb/subscription_lists/1234"
      },
     "opt_in_date":"2017-01-15T15:34:52Z",
     "opt_out_date":"2017-02-18T15:34:52+0000",
     "opt_out_reason":"user_opt_out",
     "source": {
         "acquisition_campaign":"C123456"
         }
   }
}

`Opt_out_reason` values

Opt-out reason	Description
`disconnect`	The device associated with the subscription was disconnected
`list_archived`	The list associated with the subscription was archived
`bulk_opt_out`	The subscriber was included in a bulk opt-out file
`failed_at_carrier`	An error from the carrier was received when attempting to deliver an SMS to the device
`obsolete_carrier`	Device was on a carrier that is no longer supported by Vibes
`platform_opt_out`	The subscription was removed manually using the Vibes Platform
`keyword_opt_out`	The subscription was removed after receiving a STOP keyword from the device
`api_opt_out`	The subscription was removed via the Subscription API
`user_opt_out`	Default when no other reason is specified.
`button_opt_out`	Opted out via the "subscriptions" tab in the Campaign Manager UI

Vibes may add additionalopt_out_reason options in the future.

Additional Resources

Client Certificate Authentication for Callbacks from the Vibes Platform