Data Action Concepts

Overview

Spoke supports data actions as a mechanism for customizing organization specific work flows. They are useful for configuring additional call rules, such as blocking outbound calls to specific phone numbers, or overriding the caller ID shown on outbound calls.

To get started, you will need to configure a data action in the Spoke Account Portal. You will need to provide a valid, publicly routable HTTPS URL that accepts GET or POST requests with the application/json content type.

Spoke will invoke this URL with the corresponding payload when performing a data action.

For security reasons, we strongly recommend that you ensure requests to your endpoint come from Spoke. The easiest method to validate that a request was sent via Spoke is to verify the signature.

Securing Data Actions

Verifying the signature

A request is considered valid based on the following conditions:

• The x-spoke-timestamp header is a valid UNIX timestamp, and represents a time sent within the last 5 minutes (using millisecond precision). This header allows the consumer to validate when a request was sent, to avoid replay attacks.
• The x-spoke-signature header is formatted as sha256=<HMAC algorithm cipher text>, and it contains the correct hash based on the hexadecimal representation of the SHA256 HMAC algorithm with the signing secret applied to <x-spoke-timestamp header value>.<request data>.
  • The calculated hash includes the timestamp to ensure that an attacker cannot modify the timestamp without also invalidating the message signature.
  • The source of <request data> depends on the HTTP method used:
    • For GET requests, it is the request URL including the query parameters
    • For POST requests, it is the raw request body

A request can be validated via the following:

Code
const isValidSpokeRequest = (requestData: string, signingSecret: string, spokeTimestamp: number, spokeSignature: string): boolean => {

  // Determine if timestamp is valid
  const isValidTimestamp = (Date.now() - spokeTimestamp) <= 300000; // 5 x 60 x 1000
  if (!isValidTimestamp) {
    return false;
  }

  // Determine if the signature is valid
  const [algorithm, cipher] = spokeSignature.split("=");
  const body = `${spokeTimestamp}.${requestData}`

  const h = crypto.createHmac(algorithm, signingSecret);
  h.update(body);
  return h.digest("hex") === cipher;
}

Delivery Attempts

Spoke will attempt to deliver Data Action events to your server once. To successfully invoke the data action, your endpoint must respond with a valid response payload within 2 seconds of the HTTP request being received.

Failure to return a response within the timeout period will not be treated as an error condition. If your endpoint does not return a response within the timeout period, the call will proceed as planned, using the original configuration for the call.

Available Data Actions