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 our webhook notification system, you will need to create a subscription in your Brightback dashboard. Head over to Settings > Alerts & Webhooks, scroll to the bottom and click Add.  You will be prompted with a menu item that allows you to enter the URL and choose your triggers.  

  Brightback will provide a shared secret that will be used to sign all events prior to transmission using the HMAC sha1 algorithm. The signature is generated automatically at the time the subscription is created.  The signature will be placed in the request header: “X-Hub-Signature” and should be used to verify whether or not the event payload is authentic. 
You'll be able to view the secret by viewing the webhook details by clicking on the pencil icon. 

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 twelve 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.

Trigger Description
Page loaded Any visit to a cancel experience including page refreshes.
Modal Opened Viewed a modal offer
Deflect Left the page
Cancel Clicked cancel
Send email Accepted an offer on the send message modal
Link Left the page via a URL
Intercom chat Initiated an intercom chat
Accepted Offer Accepted an offer
Save Previously deflected user did not cancel (30 days by default)
Nevermind Clicked nevermind
Accepted LA Offer Accepted a Loss Aversion Offer
Accepted Modal Offer Accepted a Modal Offer


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
    }
HTTP response codes:
By default we consider responses in the 200's to be a success. In the event you receive an event and do not wish to process it, please respond with code 422.
e.g. If you are filtering out certain offers by parsing the payload.  Send a 422 response code if you received it but do not wish to perform any downstream processing.  
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