Search Unity

Webhooks and Slack Notifications in Unity Cloud Build

September 7, 2016 in Games | 6 min. read
image01
image01
Share

Unity Cloud Build is a continuous integration service for games and apps built in Unity. Unity Cloud Build makes it simple and easy to create and share builds of your game, letting you and your team iterate faster and always be on the same page. Setting up Unity Cloud Build takes seconds and works with your existing source control repository.

Unity Cloud Build now supports webhooks! Webhooks are a simple and flexible way to receive event notifications in near-real time. In this article, we’ll discuss webhooks in more depth, what kind of events are supported, and how to configure webhooks using the Unity Cloud Build API.

What are webhooks?

Webhooks are event callbacks from Unity Cloud Build, where Unity servers send messages to your web servers to let them know what’s happening. We do this using HTTP POST to deliver a payload related to the event that triggered the callback. Currently, Unity Cloud Build triggers events related to build status updates. Over time we will be expanding these notifications to include events related to project configuration changes, permission changes, and many more.

Unity Cloud Build supports hooks at both the Organization level and Project level. Organization level hooks are sent for events related to all projects belonging to an organization. Project level hooks are only sent for events related to a specific project. While both types of hooks are nearly identical in configuration, we will focus on Project level events for this tutorial; to read more about organization hooks, see the Cloud Build API Documentation.

Supported Events

EventTrigger Condition
ProjectBuildQueuedWhen a build target is queued for building
ProjectBuildStartedWhen a build starts
ProjectBuildRestartedWhen an internal error occurs and the job is restarted
ProjectBuildSuccessWhen a build finishes successfully
ProjectBuildFailureWhen a build finishes with a failure condition
ProjectBuildCanceledWhen a build in progress is canceled

Webhook payload

A webhook delivery includes detailed information related to the delivery event (HTTP headers) and the new resource state (HTTP body) of the resource related to the event. In the case of project build events, the state of a build in progress is included as the payload.

Event Headers

NameDescription
X-UnityCloudBuild-HookIdThe record ID of the hook
X-UnityCloudBuild-EventThe name of the event that triggered this hook
X-UnityCloudBuild-DeliveryIdA unique UUID that identifies this delivery instance
X-UnityCloudBuild-SignatureThe SHA256 HMAC signature of the payload when a secret is defined


Example Delivery

POST / HTTP/1.1

X-UnityCloudBuild-Event: ProjectBuildQueued
X-UnityCloudBuild-HookId: 7
X-UnityCloudBuild-DeliveryId: 81a4ab67-0176-4e4c-8ab2-bd0ab7d3cc70
Content-Type: application/json

{
   "projectName":"My Project",
   "buildTargetName":"Mac desktop 32-bit build",
   "projectGuid":"0895432b-43a2-4fd3-85f0-822d8fb607ba",
   "orgForeignKey":"13260",
   "buildNumber":14,
   "buildStatus":"queued",
   "startedBy":"Build User <builduser@domain.com>",
   "platform":"standaloneosxintel",
   "links":{
      "api_self":{
         "method":"get",
         "href":"..."
      },
      "dashboard_url":{
         "method":"get",
         "href":"..."
      },
      "dashboard_project":{
         "method":"get",
         "href":"..."
      },
      "dashboard_summary":{
         "method":"get",
         "href":"..."
      },
      "dashboard_log":{
         "method":"get",
         "href":"..."
      }
   }
}

Creating and managing webhooks

You can add webhooks to your project from the Unity Cloud Build website. Visit your project’s history page, then click on the “Notifications” tab.

image01

Click the “Add New Webhook” button to add a new webhook:

image02

From here you can enter the URL on your web server that’s been configured to accept webhooks, and select which types of events you’d like to be notified about.

Slack notifications

If your team uses Slack for communication, you know how powerful incoming webhooks can be and would probably love to see these build events from Cloud Build integrated into your workflow. We've got you covered! From your project’s Notifications page, you can also configure Unity Cloud Build to send notifications to a specific channel in Slack.

Click the “Add to Slack” button, which will prompt you to log into your team’s Slack service, then pick the specific user or channel that you’d like notifications sent to. The build notifications look like this, including the status of the build and a link directly to the project:

image00

Advanced: webhooks using the Unity Cloud Build API

You can also use the Unity Cloud Build API to create, view, and modify webhooks. For these examples, we will use CURL to send requests to the API to setup a new webhook. To get started, you will need your Unity Cloud Build API key, which you can find on the preferences page of the Unity Cloud Build website.

Creating a project webhook

To add a project webhook, you’ll need a few pieces of information to build the API call. First, find the orgid and projectid of your project. These can be found in the URL of the project’s history page on the Cloud Build website:

image03

API Request

POST /api/orgs/{orgid}/projects/{projectid}/hooks

Request Parameters

NameTypeDescription
hookTypestring(Required) Type of hook. This should be web for now - other hook types will be coming in the future.
eventsarray(Required) List of events to listen to for this hook. See event table above for the complete list.
configobject(Required) Configuration parameters. Options are described below.

 

Configuration Options

NameTypeDescription
urlstring(Required) HTTP or HTTPS endpoint to send hook payloads
encodingstring(Default: “json”) Either json or form, depending on the desired POST body format.
sslVerifyboolean(Default: true) Verify SSL certificates of SSL endpoints.
secretstringIf set, used to compute the SHA256 HMAC signature of the hook body and adds a X-UnityCloudBuild-Signature header to the payload. Useful to validates authenticity of requests when sending to a non-SSL (HTTP) endpoint.

Example Request Body

{
  "hookType": "web",
  "events": [
    "ProjectBuildStarted",
    "ProjectBuildSuccess",
    "ProjectBuildFailure"
  ],
  "config": {
    "url": "http://requestb.in/1go1tjj1"
  }
}

Putting it all together - example with CURL

Here is an example of creating a webhook with CURL. This is tested on MacOS; on other platforms you may have to make slight modifications.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer [YOUR API KEY]" \
-d '{"hookType":"web","events":["ProjectBuildStarted","ProjectBuildSuccess","ProjectBuildFailure"],"config":{"url":"http://requestb.in/1go1tjj1"}}' \
https://build-api.cloud.unity3d.com/api/orgs/[YOUR ORGID]/projects/[YOUR PROJECTID]/hooks

Response

{
  "hookType": "web",
  "events": [
	"ProjectBuildStarted",
	"ProjectBuildSuccess",
	"ProjectBuildFailure"
  ],
  "config": {
	"encoding": "json",
	"sslVerify": true,
	"url": "http://requestb.in/1go1tjj1"
  },
  "active": true,
  "id": 0
}

That's it! You have successfully setup a webhook for your project. To test it out, start a new build and monitor the logs for your webhook request endpoint. If you are using RequestBin for testing, simply reload the page for the RequestBin URL to refresh the request history.

To learn more about using the API to manage webhooks, including listing, removing, and editing, refer to the Webhooks section of the Cloud Build API documentation.

Conclusion

Webhooks are a powerful tool to help you deeply integrate Unity Cloud Build into your development process. Webhooks are accessible now through the Unity Cloud Build API and web dashboard. If you have thoughts on what kinds of events you would like to see next for Webhooks, or if you would really like to see other custom webhook types like Slack, please share your thoughts here in the comments section!

Unity Cloud Build is built right into Unity, and included in Unity Personal, Plus, and Pro. Click here to get started now for free!

September 7, 2016 in Games | 6 min. read