Setting Up a Generic Webhook

What is a Webhook?

Webhooks allow external services like Slack to be notified when certain events happen within your Balto project. When a specific event occurs, a POST request will be sent to the URL you've provided.

In this article, we breakdown the different types of triggers along with its parameters that you'll need to set up your generic webhook. 

Set Up Your Generic Webhook

Types of Triggers (Events)

Here are the different types of triggers that are available.

Trigger name (Events)
Description
The latest version is delivered When the developer distributes the latest version of the app/website
Feedback is sent When a member of the project sends a feedback (screenshot/video clip)
Feedback is edited When a member of the project has edited their feedback details
Feedback is deleted When a member of the project has deleted the feedback that they sent
the status of a feedback is updated When someone has updated the feedback status (To do, in progress, Done)
A comment is sent When someone has left a comment on a feedback (screenshot/video clip)
A comment is updated
When a member of the project updates/edits their comment 
A comment is deleted When a member of the project has deleted their comment

Content Type

If the content type that you select is  JSON, the request will be sent with JSON String parameters.
If the content type is Formpayload={JSON String} the payload details will be included. 

If You Have Entered a Secret Value

If you have entered in a value in the  Secret field, a character string for which the parameters have been hashed through HMAC + sha1 using values of Secret will be entered under the HTTP Header through the HTTP_X_BALTO_SIGNATURE key.

If the content type is  Form, only the hashed values for payload= the removed portion will be entered. Using these values, please verify the values for the receiving side of Webhook.

Ruby on Rails Sample Code(xxx_controller.rb)

require "openssl"

class XxxController < ApplicationController
  def webhook
    secret = "my_secret_str"

    request_header_signature = request.headers[:HTTP_X_BALTO_SIGNATURE]
    signature = OpenSSL::HMAC.hexdigest("sha1", secret, request.body.read)

    if signature != request_header_signature
      puts "incorrect signature..."
    else
      puts "correct signature!!"
    end
  end
end

Parameters

The latest version is delivered

  • file_byte_size will be null for mobile web projects
  • For mobile web projects,  has_sdk will be displayed as false
{
  "action": "uploaded",
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

Feedback is sent

  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
  "action": "created",
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

Feedback is edited

  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "changed",
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

Feedback is deleted

  • For screenshot only feedback, make sure under movie_url it is displayed as null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback, make sure cpu_usage memory_usage disk_usage battery all show as null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "changed",
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

The status of the feedback is updated

  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "changed",
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  },
  "user": {
    "id": 14,
    "name": "User changed status",
    "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
  }
}
TOP

A comment is sent

  • For text only comments, attachment_url will be null 
  • Under mime_type, all text comments will be text/plain and if there's an attachment_url  the MIME_TYPE will match the file type
  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "created",
  "comment": {
    "id": 65,
    "comment": "Comment body",
    "attachment_url": "https://xxx.xxx.xxx/Comment.png",
    "mime_type": "image/png"
  },
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

A comment is edited

  • For text only comments, make sure under attachment_url it is displayed as null 
  • Under mime_type, for comments in text, it will be displayed as text/plain and if there's an attachment_url MIME_TYPE will be included
  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "changed",
  "comment": {
    "id": 65,
    "comment": "Comment body",
    "attachment_url": "https://xxx.xxx.xxx/Comment.png",
    "mime_type": "image/png"
  },
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}
TOP

A comment is deleted

  • For text only comments, make sure under attachment_url it is displayed as null 
  • Under mime_type, for comments in text, it will be displayed as text/plain and if there's an attachment_url MIME_TYPE will be included
  • For feedback only screenshots, movie_url will be null
  • For feedback only screenshots, gif_url will be null
  • Note: For feedback posted before 9/22/2017, gif_url will be null
  • For video clip feedback,  cpu_usage memory_usage disk_usage battery will all be null
  • file_byte_size will be null for mobile web projects
  • For mobile web projects which include has_sdk please make sure it is false
{
  "action": "deleted",
  "comment": {
    "id": 65,
    "comment": "Comment body",
    "attachment_url": "https://xxx.xxx.xxx/Comment.png",
    "mime_type": "image/png"
  },
  "feedback": {
    "id": 12,
    "body": "Feedback body",
    "image_url": "https://xxx.xxx.xxx/FeedbackImage.png",
    "thumbnail_url": "https://xxx.xxx.xxx/FeedbackThumbnailImage.png",
    "device_os_version": "10.3.3",
    "device_model": "iPhone7",
    "device_size": "5.5 Inches",
    "device_region": "JP",
    "inserted_at": "2017-07-31T00:00:00.000000Z",
    "updated_at": "2017-07-31T00:00:00.000000Z",
    "movie_url": "https://xxx.xxx.xxx/Movie.mp4",
    "gif_url": "https://xxx.xxx.xxx/Feedback.gif",
    "status": "ToDo or In Progress or Done",
    "cpu_usage": "4.4",
    "memory_usage": "53MB",
    "disk_usage": "83.02/119.20(GB)",
    "battery": "74.0 Unplugged",
    "category": "Feedback or Design or Idea or Bug or Other",
    "user": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "build": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "icon_url": "https://xxx.xxx.xxx/AppIcon.png",
    "version_name": "3.1.1",
    "numbering": 2,
    "file_byte_size": 7005208,
    "release_note": "Release note",
    "has_sdk": true,
    "uploader": {
      "id": 12,
      "name": "Balto User Name",
      "avatar_url": "https://xxx.xxx.xxx/Avatar.png"
    }
  },
  "project": {
    "id": 32,
    "name": "Balto Project Name",
    "platform": "Mobile Web or iOS or Android"
  }
}

The Japanese version of this article can be found here: https://balto-ja.helpscoutdocs.com/article/149-generic-webhook

Still need help? Contact Us Contact Us