Responding to a Yetto request

Custom connections require an endpoint to access. This can be in your application or in one of your backend services. When setting up an endpoint for this connection, there are a few things to keep in mind:

• The service will need to accept a GET request from Yetto with a hashed signature in the X_YETTO_SIGNATURE header.
• The service will need to be validate the request with a signing secret. We'll give you the signing secret when you first set up the connection.
• Your service will use the signing secret to decrypt the request parameter containing the payload from Yetto.
• The service will need to respond to all requests within three seconds. Yetto will only display data that comes back within that time.
• The service will need to respond to the request with valid JSON in the response body.
• The service will need to respond to a test request during setup.
• Yetto sends hashed data as a path parameter in the GET request. The path is appended to the URL path you set up in the webhook.

Let's walk through some of those items together.

Accepting and validating Yetto's request

When you first set up a customer connection, we'll share a signing secret with you. The signing secret will not be available on that page in the future, so be sure to copy and save it when first setting up the connection. That secret will be used to encode the payload of the GET request, the result of which can be compared to the X_YETTO_SIGNATURE header to confirm that the request came from us.

To validate the request:

1. Get the signature value in the X_YETTO_SIGNATURE header of the Yetto GET request.
2. Remove the beginning characters "sha256=" from the signature value; the rest of the value is the signature string you'll compare against later.
3. Get the path parameter string of the GET request and hash it, using the signing secret as the key.
4. Take the hex digest of the resulting hash, using the HMAC-SHA256 algorithm.
5. Compare the hex digest you calculated to the signature value in the X_YETTO_SIGNATURE header of the request. If they match, the request is a legitimate Yetto customer connection request.

An example in Ruby on Rails might look like this:

# Get the Yetto header signature value
yetto_signature = request.headers.fetch("X_YETTO_SIGNATURE", "")
hmac_header = yetto_signature.split("sha256=").last

# Calculate the hmac authentication digest using your signing secret
encoded_yetto_payload =  params['splat'].first
calculated_hmac = OpenSSL::HMAC.hexdigest(SHA256_DIGEST, SIGNING_SECRET, encoded_yetto_payload)

# Compare the calculated digest to the signature value in the header
return true if ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, hmac_header)

Accept and respond to a Yetto request

Once you've validated that the request has come from Yetto, you can use the signing secret to decrypt Yetto's conversation payload. The payload is encrypted with the aes-256-gcm OpenSSL Cipher. Many languages have native implementations for decrypting these types of messages. For example, in Ruby on Rails, one can use:

ActiveSupport::MessageEncryptor.new(SIGNING_SECRET, url_safe: true, serializer: :json).decrypt_and_verify(encoded_yetto_payload)

The GET request parameter that Yetto sends will have data that looks like this:

{
    "yetto": {
        "conversation": {
            "author": {
                "name": "user@example.com",
            },
            "inbox": "ibx_01J3RB6WMJDPE5R84X0JVX3YX9",
        },
    }
}

Use that to assemble data that you want to display in the conversation sidebar. You have three seconds to respond to Yetto's request with valid JSON. Yetto's customer connections accept JSON responses that look like this:

{
    "version": "2024-03-06",
    "customer": {
        "id": "customer_12345",
        "last_active": "10/15/2015"
        "name": "Kelly Customer",
        "plan_type": "Business"
    },
    "sections": [
        {
            "type": "link",
            "title": "Link to customer details",
            "description": "Application data",
            "href": "https://example.com/customer/{{ data.customer.id }}"
        },
        {
            "type": list,
            "title": "List section",
            "items": [
                {
                    "description": "Name",
                    "value": "{{ data.customer.name }}"
                },
                {
                    "description": "Plan type",
                    "value": "{{ data.customer.plan_type }}"
                },
                {
                    "description": "Last active",
                    "value": "{{ data.customer.last_active }}"
                }
            ]
        }
    ]
}

The version string, customer object, and sections array are required fields.

The version string is 2023-03-06. We will update our documentation if and when this changes.

The customer object can contain data to be used in the sections fields. We use Liquid templating to populate fields, so you can store data here if you want to use it across more than one section fields.

The sections array contains the data you want displayed in the conversation sidebar in Yetto. It must be an array of valid objects, with a maximum of three sections.

Currently, the section types we accept are link and list.

Section links

A link can contain any URL that you want your Support team to have access to in the Yetto conversation. This could be a link to an admin page in your system or a link to a third-party billing tool that you use. This section has the following fields:

Field	Data type	Required
description	string	no
href	string	yes
title	string	no
type	string	yes

Section lists

A list is an array of objects showing data that you want to see when viewing the conversation. Lists have the following fields:

Field	Data type	Required
items	array	yes
title	string	no
type	string	yes

The items objects have following fields:

Field	Data type	Required
description	string	no
value	string	yes

Using the customer object

The customer object is available for you to populate and use however you need it. When referencing customer values, make sure to format them like this:

{{ data.customer.key }}

Pay attention to the double braces and the data.customer structure.

Responding to a test request during setup

During the initial setup of a customer connection, Yetto will send a test request to your endpoint. That request can be validated using the signing secret as all other Yetto requests will be. This test request, however, will contain a X_YETTO_RECORD_TYPE header with a value of verification. The body will be encrypted with the same aes-256-gcm OpenSSL cipher, and when decrypted, looks like this:

{
    "yetto": {
        "challenge": "39e34f256caed94513592cad6a89fce498da6aa1"
    }
}

Your system will need to return this challenge string to Yetto within three seconds. The test response should look like this:

{
    "challenge": "39e34f256caed94513592cad6a89fce498da6aa1"
}

Once we receive the correct challenge response from your endpoint, you'll be able to complete the setup process.