Receive data via Webhook

Here's how Yofi sends prediction results back to partner, by calling partner provided API.

Partner needs following:

• Provide an API to receive the result from Yofi

• Use the secret key(provided by Yofi) to verify the signature of the event payload, the signature is put in the HTTP header as x-signature-sha256 using base64-encoded SHA-256 HMAC algorithm.

Sample python code to validate X-Signature-SHA256

import hashlib
import hmac
import base64
payload_body = """{yofi_prediction_fields:"...."}""" # json string received from Yofi
payload_sign = http_headers.get("x-signature-sha256")
partner_secret = "secret_key_provided_by_yofi"
digest = hmac.new(partner_secret.encode('utf-8'),
                  msg=payload_body.encode('utf-8'),
                  digestmod=hashlib.sha256).digest()
sign_sha256 = base64.b64encode(digest).decode('utf-8')
return hmac.compare_digest(digest_base64, signature_header) # True/False

Example data push request from Yofi to Partner

curl --location 'https://yofi-result-webhook.partner.com' \
--header 'Content-Type: application/json' \
--header 'x-signature-sha256: YzEPMmi38Huv7qQ4wD7dO6Y1j0rXlv3izoyL8YVKW9k=' \
--data '{
  "shop_url": "aaa.myshopify.com",
  "entity_type": "order || customer',
  "entity_id": "123456",
  "predictions":  {
      "bot_abuse_score": {
         "prediction_name": "bot_abuse_score",
         "prediction_value": "low/medium/high",
         "justification": "High frequency of orders flagged by previous checks.",
         "indicators": [
           {
              "name": "Repeated resell pattern observed",
              "is_risk": true  //true for risk, false for trust
            }
          ]
      },
      "return_abuse_score": {
          "prediction_name": "return_abuse_score",
          "prediction_value": "low/medium/high",
          "justification": "High frequency of orders flagged by previous checks.",
          "indicators": [
             {
                "name": "Repeated resell pattern observed",
                "is_risk": true  //true for risk, false for trust
              }
            ]
      }
      "other_scores....": {}
  }
}'

Payload fields description

1. shop_url:

   • Description: The URL of the Shopify store where the event occurred.

   • Example: "aaa.myshopify.com"

2. entity_type:

   • Description: Specifies the type of entity that the prediction is for. Possible values are order or customer.

   • Example: "order"

3. entity_id:

   • Description: The unique identifier for the entity (order or customer) being predicted.

   • Example: "123456"

4. predictions:

   • Description: A dict of predictions related to the entity, including scores and justifications from different prediction models.

   • Type: Dict of prediction objects

   • Key: prediction_name

     • Description: The name of the prediction score being reported, such as bot_abuse_score or return_abuse_score.

     • Example: "bot_abuse_score"

   • Value fields

     • prediction_name:

       • same as the Key

     • prediction_value:

       • Description: The value of the prediction score indicates the level of risk or trust. Possible values are low, medium, or high.

       • Example: "high"

     • justification:

       • Description: A brief explanation or reason for the prediction score.

       • Example: "High frequency of orders flagged by previous checks."

     • indicators:

       • Description: A list of indicators that support the prediction score.

       • Type: Array of indicator objects

         • name:

           • Description: The name or description of the specific indicator.

           • Example: "Repeated resell pattern observed"

         • is_risk:

           • Description: A boolean value indicating whether the indicator is a risk (true) or a trust factor (false).

           • Example: true