Webhooks

Receive signed HTTP calls from flows and automations when something happens in Helios.

Flows and automations can call your server with a webhook action. When the step runs, Helios sends an HTTP POST to the URL you configure, so you can sync activity into your own systems in real time.

Configure a webhook action

Add a Webhook action to a flow or a legacy automation. You provide:

• URL: the HTTPS endpoint Helios should call.
• Payload (optional): a custom JSON object included with every call, useful for routing or shared secrets on your side.

Request format

Helios sends a POST request with a JSON body.

From a flow:

{
  "trigger": "formSubmission",
  "flow": "665f1c2ab8d3e40012a4f9d1",
  "payload": { "your": "custom payload" },
  "data": {
    "gym": "662a8e12c4f7b30011d2e8a3",
    "customer": "664b9d34e1a2c50013f6b7c9"
  }
}

From a legacy automation, the body is the same without the flow field.

Verify the signature

Every call includes a helios-authorization header so you can confirm the request really came from Helios. The header is a JWT signed with Helios’s private key using ES256:

• The issuer (iss) is helios.
• The token contains a host claim matching your endpoint’s host.
• It expires 1 minute after signing, so replayed requests fail verification.

Verify the token against the Helios public key with any standard JWT library, and check that the host claim matches your own hostname:

import { createVerifier } from "fast-jwt";

const verify = createVerifier({
  key: HELIOS_PUBLIC_KEY,
  algorithms: ["ES256"],
  allowedIss: ["helios"],
});

const claims = verify(request.headers["helios-authorization"]);
if (claims.host !== "your-domain.com") {
  throw new Error("Unexpected host claim");
}

Respond quickly

Helios does not retry failed webhook calls. Respond with a 2xx status as fast as possible, and queue any heavy processing on your side.

Sending data the other way

To push contacts into Helios from your systems, see Push contacts.