Webhooks

Webhook

Webhooks are the most basic Destination to set up, and involve Terra making a POST request to a predefined callback URL you pass in when setting up the Webhook.

They are automated messages sent from apps when something happens.

Terra uses webhooks to notify you whenever new data is made available for any of your users. New data, such as activity, sleep, etc will be normalised and sent to your webhook endpoint URL where you can process it however you see fit.

After a user authenticates with your service through Terra, you will automatically begin receiving webhook messages containing data from their wearable..

Security

Exposing a URL on your server can pose a number of security risks, allowing a potential attacker to

Launch denial of service (DoS) attacks to overload your server.
Tamper with data by sending malicious payloads.
Replay legitimate requests to cause duplicated actions.

among other exploits.

In order to secure your URL, Terra offers two separate methods of securing your URL endpoint

Payload signing

Every webhook sent by Terra includes an HMAC-based signature header terra-signature, which takes the form:

t=1723808700,v1=a5ee9dba96b4f65aeff6c841aa50121b1f73ec7990d28d53b201523776d4eb00

In order to verify the payload, you may use one of Terra's SDKs as follows:

Terra requires the raw, unaltered body of the request to perform signature verification. If you’re using a framework, make sure it doesn’t manipulate the raw body (many frameworks do by default)

Any manipulation to the raw body of the request causes the verification to fail.

import os

from flask import Flask, jsonify, request
from terra.utils.verify_signature import verify_terra_webhook_signature

app = Flask(__name__)

signing_secret = os.getenv('SIGNING_SECRET')  # Your signing secret from Terra


@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('terra-signature')
    body = request.get_data(as_text=True)

    if signature is None:
        return jsonify({"error": "terra-signature header missing"}), 400

    try:
        is_valid = verify_terra_webhook_signature(
            payload=body, signature_header=signature, signing_secret=signing_secret
        )
        if not is_valid:
            return jsonify({"error": "Invalid signature"}), 400

        # Process the webhook data here
        webhook_data = request.get_json()
        print(f"Received valid webhook data: {webhook_data}")

        return jsonify({"message": "Webhook received successfully"}), 200

    except Exception as e:
        return jsonify({"error": str(e)}), 500


if __name__ == '__main__':
    app.run(port=8000)

const express = require("express");
const { verifyTerraWebhookSignature } = require("terra-api");

const app = express();

// Use the built-in Express middleware to parse raw JSON bodies.
// This must be placed before the webhook endpoint.
app.use(
    express.raw({
        inflate: true,
        limit: "4000kb", // Set a limit appropriate for your use case
        type: "application/json",
    })
);

// Make the route handler function async
app.post("/consumeTerraWebhook", async (req, res) => {
    try {
        const signature = req.headers["terra-signature"];
        const secret = process.env.TERRA_SECRET;

        // First, verify the signature. The function will throw an error if verification fails.
        // The req.body is a Buffer, which is the expected format.
        await verifyTerraWebhookSignature(req.body, signature, secret);

        // If verification is successful, send a 200 OK response immediately.
        res.sendStatus(200);

        // Process the data *after* responding to prevent timeouts.
        const data = JSON.parse(req.body.toString("utf8"));
        console.log("Received & Verified Terra Webhook Data:");
        console.log(JSON.stringify(data, null, 2));

    } catch (error) {
        // If verifyTerraWebhookSignature throws an error, catch it here.
        console.error("Webhook verification failed:", error.message);
        return res.sendStatus(401); // Respond with Unauthorized
    }
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
    console.log(`Server started on http://localhost:${port}`);
});

import co.tryterra.terraclient.WebhookHandlerUtility;

// Using the Spark framework (http://sparkjava.com)
public Object handle(Request request, Response response) {
    String payload = request.body();
    String sigHeader = request.headers("terra-signature");

    // Find your secret on https://dashboard.tryterra.co/dashboard/connections
    WebhookHandlerUtility handlerUtility = new WebhookHandlerUtility("SIGNING_SECRET");

    boolean validSignature = handlerUtility.verifySignature(sigHeader, payload);

    if (!validSignature) {
        response.status(401);
        return "";
    }

    // Deserialize the object inside the event & handle the event
    // ...
    response.status(200);
    return "";
}

We recommend that you use our official libraries to verify webhook event signatures. You can however create a custom solution by following this section.

The terra-signature header included in each signed event contains a timestamp and one or more signatures that you must verify.

the timestamp is prefixed by t=
each signature is prefixed by a scheme. Schemes start with v, followed by an integer. (e.g. v1)

terra-signature:
t=1492774577,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,
v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

Terra generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, ignore all schemes that aren’t v1

To create a manual solution for verifying signatures, you must complete the following steps:

Step 1: Extract the timestamp and signatures from the header

Split the header using the , character as the separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.

Step 2: Prepare the signed_payloadstring

The signed_payload string is created by concatenating:

The timestamp (as a string)
The character .
The actual JSON payload (that is, the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time-string comparison to compare the expected signature to each of the received signatures.

IP Whitelisting

IP Whitelisting allows you to only allow requests from a preset list of allowed IPs. An attacker trying to reach your URL from an IP outside this list will have their request rejected.

Terra sends all outbound requests (webhooks, database connections, etc.) from the same set of IPs. See the full IP list on the data destinations overview page.

Retries

If your server fails to respond with a 2XX code (either due to timing out, or responding with a 3XX, 4XX or 5XX HTTP code), the request will be retried up to 10 times with exponential backoff. The delay doubles each time, starting at 30 seconds and capping at 8 hours:

Retry

Delay

1st

30s

2nd

1 min

3rd

2 min

4th

4 min

5th

8 min

6th

16 min

7th

32 min

8th

1h 4min

9th

2h 8min

10th

4h 16min

After 10 failed attempts, the event is dropped.

Timeout handling

Terra waits 8 seconds for your server to respond before considering the request timed out.

When your endpoint repeatedly times out, Terra activates a per-destination circuit breaker to avoid overwhelming your server. While the circuit is open, new events for that destination are held back with exponential backoff (same 30s-to-8h schedule). The circuit automatically closes once the backoff period expires and your server responds successfully.

The circuit breaker is only triggered by timeouts — other errors (4xx, 5xx, connection refused) trigger normal per-event retries without opening the circuit.

Ping mode (S3 payload delivery)

For high-volume integrations or large payloads, Terra supports a ping mode that keeps webhook payloads small. Instead of sending the full data payload in the POST body, Terra uploads it to cloud storage and sends a lightweight summary with a pre-signed download URL.

When ping mode is enabled, your webhook receives:

{
  "status": "success",
  "type": "s3_payload",
  "url": "https://presigned-download-url.example.com/...",
  "expires_in": 300
}

url — A pre-signed link to the full data payload, hosted on Terra's infrastructure. Download it with a GET request.
expires_in — URL validity in seconds (300 = 5 minutes).

How to process ping mode payloads:

Receive the webhook POST as usual and verify the signature.
Check if the type field is "s3_payload".
Download the full payload from the url field using a GET request.
Process the downloaded JSON as you would a normal webhook payload.

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.get_json()

    if data.get("type") == "s3_payload":
        # Ping mode — download the full payload from the URL
        response = requests.get(data["url"])
        payload = response.json()
    else:
        # Normal mode — the full payload is in the POST body
        payload = data

    # Process payload as usual
    process(payload)
    return "", 200

Authentication and connection events (auth success, deauth, etc.) are always delivered inline in the POST body, even when ping mode is enabled. Only data payloads use the S3 URL delivery.

To enable ping mode, submit a request to Terra support. It is configured per destination and does not require any changes to your webhook URL.

PreviousSetting up data destinations NextSQL database (Postgres, MySQL)

Last updated 2 days ago

Was this helpful?

hashtagWebhook

hashtagSecurity

hashtagPayload signing

hashtagIP Whitelisting

hashtagRetries

hashtagTimeout handling

hashtagPing mode (S3 payload delivery)