Skip to main content
Webhooks are currently only available to apps and cannot be configured by merchants for their own accounts.

​
Configure webhook sending

The first step to receiving webhooks is configuring your webhook URL. Once setup, you will then be able to specify the topics to which you’d like to subscribe.
  1. In the Partner Portal, go to Apps.
  2. Click on the name of the app you want to define a new activity type for.
  3. Navigate to the Webhooks page for your app.
  4. Click + Create webhook.
  5. Enter the webhook details and click Create.

​
Webhook topics

Webhook topics allow an app to subscribe to specific events that occur in Smile. Below is a list of webhook topics that an app can subscribe to.
TopicDescription
pingThis topic is used during webhook creation to verify that your webhook endpoint is functioning properly. The data portion of this webhook is an empty object.
customer/updatedOccurs when a customer is updated (including when a customer is first created).

​
Webhook bodies

Webhook bodies (payloads) are in JSON format and have a consistent structure across all topics. They contain the following parameters.
ParameterDescription
account_idThe ID of the Smile account on which the event occurred.
dataThe specific data pertaining to the webhook topic. For example, the data in a customer/updated webhook will contain a customerobject.
topicThe webhook topic. Topics contain two components: a subject and a verb separated by a slash (e.g. customer/updated).
Here is an example webhook body.
JSON
{
  "account_id": 0,
  "data": {},
  "topic": "ping"
}

​
Customer webhooks

For webhook topics with a “customer” subject (e.g. customer/updated), the data attribute in the webhook body will contain the following parameters.
ParameterDescription
customerAn object representing the customer that was updated. See the customer object for the attributes that are included.
JSON
{
  "data": {
    "customer": {}
  }
}

​
Verifying webhook signatures

In order to verify that a webhook contains legitimate data, Smile signs the contents of each webhook with a sha256 HMAC. Webhooks are signed using the app’s client secret (found in the app’s settings in the Partner Portal), and the following headers must be used to verify the signature of a webhook.
HeaderDescription
Smile-SignatureThe HMAC generated by Smile. An app will attempt to compute this signature in order to verify that the webhook is legitimate.
Smile-TimestampThe number of seconds since the Unix epoch (UTC). This value is used to prevent replay attacks.
To verify a webhook’s signature, you must perform the following steps.
  1. Concatenate the Smile-Timestamp, followed by a period (.), followed by the webhook request body.
  2. Generate a sha256 HMAC using the computed string and the app’s client secret.
  3. Compare the computed HMAC to the value of the Smile-Signature header.
  4. Verify that the timestamp is within 5 minutes of the current time.
In code, verifying a webhook signature looks like:
Ruby
require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'

def verify_webhook_signature(body, timestamp, signature)
  client_secret = ENV["SMILE_CLIENT_SECRET"]
  prepared_string = "#{timestamp}.#{body}"

  # Compute the hmac using the client secret.
  digest = OpenSSL::Digest.new("sha256")
  hmac = OpenSSL::HMAC.digest(digest, client_secret, prepared_string)
  encoded_hmac = Base64.encode64(hmac).strip

  # Verify that the webhook has been sent within the last 5 minutes.
  timestamp_plus_five_minutes = timestamp.to_i + 5 * 60
  webhook_is_fresh = timestamp_plus_five_minutes > Time.now.to_i

  # Check that the signature matches and the webhook is fresh.
  (encoded_hmac == signature) && webhook_is_fresh
end

post "/" do
  body = request.body.read
  timestamp = request.env['HTTP_SMILE_TIMESTAMP']
  signature = request.env['HTTP_SMILE_SIGNATURE']

  # Verify the webhook signature.
  verified = verify_webhook_signature(body, timestamp, signature)
  puts("Webhook verified: #{verified}")
  status 200
end
The above code snippet is functional, however in order to prevent timing attacks, a constant time string comparison function should be used when comparing signatures.

​
Responses & retries

A webhook will be considered successfully delivered if the endpoint responds with a 2xx HTTP status code within 5 seconds. During periods of high traffic (such as sale seasons or other shopping-focused times of year), apps may receive a high volume of webhooks, so asynchronous webhook processing is highly recommended. If a response is not received within the allowed time period or a non-200 status code is observed, the webhook send will be considered to have failed. If a webhook fails to send for any reason, Smile will try to send the webhook again later using an exponential backoff algorithm. If the webhook cannot be sent successfully within a 24 hour period, the webhook will be disabled across all accounts with the app installed.

​
Permissions

Every webhook topic has corresponding OAuth permissions which determine if a webhook can be sent for a given account. For example, in order to receive customer/updated webhooks, the app must be granted the customer:read permission. It is important to understand that app permissions are granted on a per-account basis. This means that an app is not guaranteed to have the same scope on all of the Smile accounts that it is installed on. As a result, an app will only receive webhooks for the subset of Smile accounts that have granted it the required permissions. Once a webhook is created via the Partner Portal and at least one user has authorized the app with one of the required permissions, the app will start to receive webhooks.