Using Webhooks

Webhooks enable Brightback to call a script on your server when an event has occurred in the Brightback cancel experience. Webhook events can be used to trigger an action in your billing system or activate another internal workflow.  

A note about your endpoint's URL and redirects:

Brightback's webhook events will not redirect if your endpoint returns a 3xx HTTP redirect code.  To ensure your endpoint's URL is correct you should perform the following test in your terminal. 

curl -v https://example.com/endpoint -XPOST 

If the response is in the 3xx range Brightback will consider the event as failed and will not retry the event. 

e.g. https://example.com/endpoint redirecting to https://www.example.com/endpoint would be recorded as a failure.  Brightback events would need to be pointed to https://www.example.com/endpoint in this example.

Implementing webhooks with BrightBack 

Brightback events are sent as POST requests to any static endpoint.  Events can be distributed to multiple endpoints or directed to a single URL. 
In order to use webhooks with cancel experience alerts the Brightback team will need to know the endpoint (URL) you would like alerts to be directed at and what alerts should be activated.  Brightback will provide a shared secret that will be used to sign all events prior to transmission using the HMAC sha1 algorithm.  The signature will be placed in request header:“X-Hub-Signature” and should be used to verify whether or not the event payload is authentic. 
For reference, our webhooks are signed using the following code:
public static String signHmacSha1(String message, String key) { 
    try {
        // Get an hmac_sha1 key from the raw key bytes 
        byte[] keyBytes = key.getBytes(StandardCharsets.UTF-8); 
        SecretKeySpec signingkey = new SecretKeySpec(keyBytes, "HmacSHA1");

        // Get an hmac_sha1 Mac instance and initialize with the signing key 
        Mac mac = Mac.getInstance("HmacSHA1"); 
        mac.init(signingkey);
        
        // Compute the hmac on input data bytes 
        byte[] rawHmac = mac.doFinal(message.getBytes(StandardCharsets.UTF-8));

        // Convert raw bytes to Hex 
        byte[] hexBytes = new Hex().encode(rawHmac);

        // Convert array of Hex bytes to a String
        return new String(hexBytes, Standard Charsets.UTF_8); 
        } catch (Exception e) {
        throw new IllegalStateException("Unable to sign message", e);
    }
}

Event Types

There are nine event types that can be individually enabled to trigger a POST request for any Brightback app. Check out our offer creation help doc for a review of offer types and actions.

  • Viewed cancel page
    • Triggered at the time the page is loaded or refreshed.
  • Deflected
    • The deflect event is sent when a canceler leaves the Brightback page either by selecting an offer or clicking on one of the never mind buttons.
  • Canceled
    • This event is triggered following a confirmed cancel.
  • Sent a message or email
    • For offers where the action is send email or send email instantly. This event is sent in parallel or in lieu of an actual email.
  • Followed a link
    • The link event is triggered for all events that take the canceler off of the page.  That includes hyperlinks to content or offer actions, clicking never mind and cancel confirmations.
  • Initiated a chat
    • Event is sent when canceler initiates an intercom chat.
  • Accepted an offer
    • The accept offer event is sent when a call to action is clicked in an offer modal or loss aversion with an offer for both send email and link action types.
  • Saved
    • This hook is sent 30 days (default timeframe) following a deflect event if the canceler does not come back to Brightback and cancel.
  • Added to watch list
    • Users are added to the watchlist if they have not confirmed a cancellation within 30 minutes of the first page load. 

Sample payload contents

Root level 

    "url": "https://www.example.com/endpoint",
    "delivery_attempts": 1,
    "created_at": "1970-01-01T00:00:00Z",
    "subscription_id": "1234567890",
    "first_sent_at": "1970-01-01T00:00:00Z",
    "id": "a7467d71-92c4-4a2d-92bb-ec315bbbb082",
    "type": "event"

The data object

Nested within the data object are several useful parameters as well as the survey, offer, browser context and fields from the JS snippet.

"data": {
    "type": "link",
	/* the type of event that was triggered.  possible values include page_loaded, deflect, cancel, send_email, link, chat, offer, save and watch_list */
    "id": "2955d62b-3b2a-46ce-ad83-204c9b99d689",
    "app_id": "1234567890",
	// your app within Brightback
    "session_id": "abcde12345",
	//unique cancel session id
    "name": "10_off.sixty_forty_column.217648e7",
	//the name of modal or page when event was triggered 
    "timestamp": "1970-01-01T00:00:00Z",
    "survey": {...},
    "offer": {...},
    "fields": {...},
    "context": {...},
  },

Values under the data.survey object

The survey key holds answers to survey questions if they were selected at the time of accepting an offer or during cancel. 

 "survey": {
            "reason_for_leaving": [
                {
                    "name": "reason_for_leaving",  
                    "value": "customer_service_was_unsatisfactory.1928377447", 
                    "tier": "tier0", //legacy 
                    "lives_on": "tier0" //legacy
                }
            ],
            "competition": "None",
            "sentiment": 10,
            "feedback": "Brightback is great!",
            "confirmation": true,
            "selected_reason": "customer_service_was_unsatisfactory.1928377447",
		//unique reason key
            "display_reason": "Customer service was unsatisfactory", 
		//reason shown to canceller
            "brightback_reason": "bad_customer_service"
		//Brightback internal reason key
       },
/* additionally a custom reason key can be added to align with your internal tracking */

Values under data.offer object

The offer key holds information relative to the modal that was displayed if the CTA in an offer is clicked.

 "offer": {
	"name": "10_off.1731427124",
		//unique name of the offer established when the offer was created
	"display_name": "$10 Off",
		//mutable name of the offer in the experience manager
	"type": "$",
		//offer type chosen during offer creation
	"category": "Discounts"
		//category of offer chosen during offer creation
       },<br>
	

Values under data.context object

The context key contains the browser context information from the client.

  "context": {
      "ip": "1.1.1.1",
      "locale": "en-US",
      "timezone": "America/Los_Angeles",
      "user_agent": "Mozilla/5.0 ...",
      "url": "https://cancel.example.com/example/cancel/abcde12345",
    },

Values under data.fields object

The fields key contains fields passed through the snippet including custom as well as standard fields that have been mapped in.  

The following code block shows a small sample of a typical payload nested in the fields object. 

"fields": {
      "standard.Owner Email": "jane@brightback.com",
      "standard.Owner First Name": "Jane",
      "standard.Owner Last Name": "Brighteyes",
	//Brightback standard fields if populated and mapped.

      "cancel.save_return_url": "https://www.example.com/return",
      "cancel.app_id": "1234567890",
      "cancel.account.created_at": "1970-01-01T00:00:00Z",
      "cancel.account.plan": "Premium",
      "cancel.account.plan_term": "monthly",
      "cancel.account.internal_id": "abcd123",
	//original payload from the JS snippet

      "cancel.custom.activity": "none",
      "cancel.custom.emails": "500",
      "cancel.custom.offer_eligible": true,
	//custom fields from the JS snippet

      "cancel.context.locale": "en-US",
      "cancel.context.timezone": "America/Los_Angeles",
      "cancel.context.user_agent": "Mozilla/5.0 ...",
	//browser context for cancel session
    }
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us