Webhooks

What are Webhooks?

Webhooks are a way to subscribe to system events so you can be notified automatically when they occur. For instance, you can subscribe to the SessionCompletedEvent in the BuildOn Business Events API and whenever a session is completed in your design center a message will be sent to an API that you control so you can pull session data and perform whatever business actions need to be done in your system.

The OpenAPI documentation can be found here: Business Events API. This is the full documentation including all accepted objects. You can even make calls to our services provided that you have an API Key.

This article will give you a brief overview of how this API can be utilized.

Subscribing

In order to receive events, you need to create a subscription. You can see all the events that we currently support by calling the events endpoint.

GET https://api.buildontechnologies.com/webhooks/buildon/events

The full results can be seen below. Currently, we only publish the SessionCompletedEvent, but more will be added in the future.

{
  "data": [
    {
      "id": "40d18e4f-6c49-4057-a8c0-dab14686141c",
      "name": "SessionCompletedEvent",
      "description": "Event that is fired when a session is completed in Veo Design Studio."
    }
  ]
}

Each event has an id, a name and a description. The description provides details of when the event will be triggered. The id is the value you will use to reference an event. The name is a human readable value for convenience.

The listing of events can be referenced without authentication. All other calls to the Business Events API require an API Key. You will also need your TenantId.

To create a subscription, you will POST a message to the subscriptions endpoint. This can be done via a tool like Postman or through our API Documentation.

POST https://api.buildontechnologies.com/webhooks/buildon/tenants/{tenantId}/subscriptions

{
  "url": "https://example.com/webhook",
  "secret": "sjkhuevrnejkkyudfvf",
  "eventId": "c1b0427a-af5f-44ff-bdcf-70440d7ef04b",
  "isActive": true
}

You will need to supply the tenantId of the tenant that you want to subscribe to. The eventId is the GUID id of the event that you want to receive notification for. The url is the url of the API where you want to receive the notification. This should be an API that you have control of. The isActive is optional. This flag lets you disable a subscription without deleting it. Any subscription with isActive set to false will not send out notifications. The secret variable is optional also. It is used to cryptographically ensure that a message you receive is valid and comes from BuildOn. This will be elaborated on below.

To subscribe to the SessionCompletedEvent you can send the following message:

{
  "url": "https://example.com/webhook",
  "eventId": "40d18e4f-6c49-4057-a8c0-dab14686141c"
}

To the following address:

POST https://api.buildontechnologies.com/webhooks/buildon/tenants/{tenantId}/subscriptions

You should receive a message that looks similar to this:

{
  "data": {
    "id": "f3dcc237-5e31-4690-8ad3-5dbd3e2c104a",
    "url": "http://api.buildontechnologies.com/webhooks/test/api/callback",
    "secret": "",
    "isActive": true,
    "event": {
      "id": "f3dcc237-5e31-4690-8ad3-5dbd3e2c104a",
      "name": "SessionCompletedEvent",
      "description": "Event that is fired when a session is completed in Veo Design Studio."
    }
  }
}

It contains the data about your subscription and the event you are referencing.

The id is the id of the subscription. It can be used to edit or delete the subscription via a PUT message.

Event Notification

Once you have an active subscription, a message will be sent to your callback URL whenever the corresponding event occurs within BuildOn’s systems.

Below is an example of a Session Completed notification message.

{
  "data": {
    "organizationId": "a7cc080c-26d9-4a20-a5a4-2cc9a1f2761a",
    "sessionId": "f3dcc237-5e31-4690-8ad3-5dbd3e2c104a",
    "sessionCompletedDate": "2025-01-09T18:34:12.8749762+00:00",
    "links": {
      "sessionSelections":"https://api.buildontechnologies.com/vds/buildon/sessions/f3dcc237-5e31-4690-8ad3-5dbd3e2c104a/selections"
    }
  }
}

The organizationId is the organization the completed session is for. The sessionId is the id of the completed session. With these values, information about a completed session can be retrieved from the VDS Integration API.

For convenience, the sessionSelections link is provided on the links object. A GET call to the sessionSelections url will return all the selections that were selected during the completed session provided that you include your API Key with the call. For more information on sessions and session selections, see the VDS Integration API documentation.

Secret

The secret is used to verify cryptographically that only BuildOn is sending messages and that the messages have not been tampered with. Your secret should be stored securely and should not be guessable.

When a webhook notification is sent and secret has been populated, a hash based on the payload and the secret is created and sent along with the payload in the x-signature-256 header. You can verify that the source and the payload are valid by computing your own hash and comparing it to the signature sent.

using System.Net.Http.Json;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// This is for example only. This value should be stored securely.
const string _secret = "some secret that no one else knows";

public bool VerifySignature(string payload, string signature)
{
    string expectedSignature = GenerateSignature(_secret, payload);

    return signature == expectedSignature;
}
 
private static string GenerateSignature(string secret, string payload)
{
    var encoding = new UTF8Encoding();
    byte[] keyBytes = encoding.GetBytes(secret);
    byte[] payloadBytes = encoding.GetBytes(payload);

    using var hasher = new HMACSHA256(keyBytes);
    byte[] hashBytes = hasher.ComputeHash(payloadBytes);
    return $"sha256={Convert.ToHexStringLower(hashBytes)";
}