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

Event Trigger Condition ProjectBuildQueued When a build target is queued for building ProjectBuildStarted When a build starts ProjectBuildRestarted When an internal error occurs and the job is restarted ProjectBuildSuccess When a build finishes successfully ProjectBuildFailure When a build finishes with a failure condition ProjectBuildCanceled When 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

Name Description X-UnityCloudBuild-HookId The record ID of the hook X-UnityCloudBuild-Event The name of the event that triggered this hook X-UnityCloudBuild-DeliveryId A unique UUID that identifies this delivery instance X-UnityCloudBuild-Signature The 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":"..." } } } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 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.

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

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:

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:

API Request

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

Request Parameters

Name Type Description hookType string (Required) Type of hook. This should be web for now – other hook types will be coming in the future. events array (Required) List of events to listen to for this hook. See event table above for the complete list. config object (Required) Configuration parameters. Options are described below.

Configuration Options

Name Type Description url string (Required) HTTP or HTTPS endpoint to send hook payloads encoding string (Default: “json”) Either json or form , depending on the desired POST body format. sslVerify boolean (Default: true) Verify SSL certificates of SSL endpoints. secret string If 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" } } 1 2 3 4 5 6 7 8 9 10 11 { "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 1 2 3 4 5 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 } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "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!