Webhook Events Documentation

Webhook Events

Organizations that have the API enabled can use webhooks to receive instant callbacks for important events within TerraTrue. Only users with the ADMIN permission have access to webhooks.

Webhook Signatures for Security

We suggest that you use a webhook signing secret to verify that the events you receive on the webhook are authentic, as this secret is known only to you and TerraTrue. You can regenerate the secret at any time, but doing so will invalidate the prior secret for anyone at your or who may have been using it.

Once you have generated a signing secret, headers like the following will appear in every webhook call you receive:

X-TerraTrue-Request-Timestamp: 1646783626
X-TerraTrue-Signature-Version: v1
X-TerraTrue-Signature: f2ee934311e2294189fc4abe2b4cf04ae0cb27d56b5d4bbe9246d64842a576d7

The X-TerraTrue-Request-Timestamp carries the Unix time of the event signature, namely the number of seconds since January 1, 1970 UTC.

The X-TerraTrue-Signature-Version declares which version of the TerraTrue signing algorithm we’re using.

The X-TerraTrue-Signature carries the computed signature.

How to Verify the Signature

To verify that the signature is authentic, perform these steps in your favorite development language:

1. Copy the generated secret from the TerraTrue user interface
2. Retrieve the X-TerraTrue-Signature-Version and X-TerraTrue-Request-Timestamp header values to variables
3. Ensure the X-TerraTrue-Request-Timestamp is not be more than 5 minutes from the current time; compare it to now and reject anything older.
4. Create a variable called basestring by joining the following strings with colons: the version, the timestamp, and the webhook request body’s raw bytes
   • Example: v1:1646783626:<request-body>
5. Use the HMAC SHA256 hashing function with your signing secret to compute the hash of the basestring, then take a hex digest of the hash value. This is the signature.
6. Ensure that the value you compute exactly matches the signature header value

Node example code to verify the signature:

signing_secret = 'MY_SIGNING_SECRET'
timestamp = request.headers['X-TerraTrue-Request-Timestamp']
version = request.headers['X-TerraTrue-Signature-Version']
signature = request.headers['X-TerraTrue-Signature']
if absolute_value(time.time() - timestamp) > 60 * 5:
return
basestring = version + ':' + timestamp + ':' + request.body()
local_signature = hmac.compute_hash_sha256(signing_secret, basestring).hexdigest()
if hmac.compare(local_signature, signature):
// accept event as authentic
receive_webhook(request)

Managing Webhooks

To add a webhook, click the Add New Webhook button at the upper right.

Enter the URL that you wish to receive the webhook events on. We support urls with https protocol only at this time.

Then select as many or as few from the numerous event types. If the event you wish to receive is not listed, please let our team know about it.

If desired, the webhook can be configured to filter for specific launches, so only events related to those launches are received. However, Launch creation and privacy settings changed events are organization-wide and will always be received if selected.

Webhook Event Data

The webhook events you receive will be simple JSON format, following the definitions below.

Common Properties

All webhook events carry a small set of common properties, detailed here.