Webhook Creation

Overview

Extole webhooks submit real-time data about your participants and their journey through programs to your own HTTPS endpoints. Extole webhooks support a variety of authentication methods and can be customized to format the request body in as needed. Our Support Team is available and equipped to help you customize your webhooks.

Webhook Configuration

Webhooks require configuration within the Extole platform. You may configure your Extole account to use webhooks by logging in and going to Tech Center > Outbound Webhooks.

You need to provide the information required for the webhook to know where and how to send your data. At the most basic level, you can configure your webhooks by including:

• Name: How we will refer to the webhook in My Extole
• Client Key: The secret / key used to verify the authenticity of the Extole integration. Client Keys can be created by navigating to the Security Center, clicking + New Key.
• The payload URL: The destination URL the webhook will GET or POST to.
• Description: An optional description for your webhook.

Advanced configuration is also optionally available to allow you more control over the structure and format of the data you’d like to receive in the request. If you need changes to the payload, the events, or the Advanced configuration, please contact your customer success or implementation manager. You can also let your Extole Team know what data you'd like to receive in the request and they can set this up for you.

Client Keys & Security

In the My Extole Security Center you can easily create Client Keys for your webhooks. We support HS256 signing, Password, Basic, OAuth, and a variety of vendor-specific variations of OAuth.

These authorization options are configurable within the Security Center in your My Extole account under the Keys section.

Webhook Signature Validation (not recommended)

The webhook signs the body of each webhook post with a client-specified secret key, specified with the webhook. The signature is passed as the header X-Extole-Signature when the event is posted.

The signature is a hash against the exact string sent in the HTTP request. It does not include the headers and it is not pretty-formatted. It looks like this:

{"type":"reward_earned","event_id":"qb3jju459ugjr2aojk5e","event_time":"2020-05-29T14:14:18.548Z","reward_id":"bf67905b4e1b41daf39c30f0","reward_supplier_name":"Advocate Account Credit","reward_supplier_id":"701e681a9e46c8b6778f3452","partner_reward_supplier_id":"Advocate Account Credit","reward_supplier_type":"CUSTOM_REWARD","person_id": "6816411215104951917","partner_user_id":"1036950000","face_value":50,"face_value_type":"USD","message":null,"schema_version":1}

The signature can be calculated against the String of JSON using HMAC256:

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;

private static final String HMAC_SHA_256 = "HmacSHA256";

public String encode(String message, String secretKey) throws Exception {
  Mac algorithm = Mac.getInstance(HMAC_SHA_256);
  SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), HMAC_SHA_256);
  algorithm.init(secretKeySpec);
  return DatatypeConverter.printHexBinary(algorithm.doFinal(message.getBytes())).toLowerCase();
}

signature = 'sha1='
  + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'),
    secret, post_body)

🚧

HMAC Validation in Node.js

Node.js has a habit of changing integer formatting when processing application/json responses. Special care should be taken if using Node.js to process the request.

Webhook Live View

Once you have a webhook configured, you'll be able to see a detailed view of it from the Outbound Webhooks page. Here you will see the top-level details of your webhook as well as a live view of the events happening.