Skip to content
Yetto Docs

Responding to a Yetto request

Webhooks require an endpoint to access. When setting up an endpoint for this connection, there are a few things to keep in mind:

  • The service will need to accept a POST 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 body containing the event payload from Yetto.
  • The service will need to respond to a test request during setup.

Let's walk through some of those items together.

Accepting and validating Yetto's request

When you first set up awebhook, 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 POST 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 query parameter string of the POST 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 webhook 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)

Responding to a test request during setup

During the initial setup of a webhook, 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 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.