Search Unity

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

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.

image01Click 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


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

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.


Response


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!

Comments are closed.

  1. common telecharger unity player

  2. I really enjoyed reading this post, and I’m happy to see that a proper explanation on this build notification feature. I have been trying to integrate this with Discord (almost like Slack) and now I think this gave me a boost! I hope to share my progress with the community soon.

    To be honest, the main aspect of using Cloud Build that, as a small indie team, I really enjoy is the the opportunity for the whole team to access the latest builds (especially those that don’t have access to the game project such as artists and musician). Not only does this allow the team to see where the game is going and most importantly it also motivates the team. Motivation is a key element to a successful indie game, and Cloud Build enables this.

    But like I said again, I’ll attempt myself to create a possibility for webhook notifications to appear on our Discord chat. Any additional help is always accepted!

  3. Integration into the pull request workflow would be fantastic. We use github, but bitbucket and gitlab also provide this workflow really well and this would make testing so much easier.

    For github, the ideal integration would be an automatic build on a PR and then report back using the github status API to inform github about the outcome.

    1. Yes this is definitely something we are interested in supporting and is already on our roadmap. Thanks for your feedback!

    2. I agree with you. Another use case I found was to trigger a new build daily on a given hour to integrate everybody’s work. We do this on the studio I currently work with. So I wrote this tool to trigger builds using the cloudbuild API. I set up a task that runs it everyday but I guess you could create a webhook for github that would do it for you everytime a pull request is created. An out-of-the-box solution would be way better though.