Skip to main content

Webhook API Integration in SA Engine

Webhooks provide a powerful method of integrating third-party software with SA Engine. They enable external applications, such as InfluxDB, Excel, Slack, Node Red GitHub, or any other system that supports HTTP based integration, to initiate communications with SA Engine, broadening the scope of what can be achieved through the system. Additionally, SA Engine can use the http: family of functions to easily make calls to other webhook endpoints.

One of the key features of SA Engine's webhook API is the ability to store and execute custom functions. This guide will walk you through the process of using this feature.

1. Defining Custom Functions​

First, you need to define your custom functions. These will be specifically for HTTP POST or GET requests, and they need to adhere to the following structures:

For HTTP POST: fn(charstring action, Record data) -> Object

For HTTP GET: fn(charstring action, Charstring param1, Charstring param2, ...) -> Object

Here are example functions for both POST and GET:

For a POST function:

create function test_webhook(Charstring action, Record data) -> charstring
  as  {
    print(action);
    print(data);
    return "test_webhook OK!";
  };

For a GET function:

create function test_webhook_get(Charstring action, Charstring a, Charstring b) -> charstring
  as concatagg(select a from number x where x in range(aton(b)));

2. Storing Custom Functions​

Once your custom functions are defined, they need to be stored for subsequent use.

To store a POST function:

add webhook:post_actions("test_webhook") = #"test_webhook";

To store a GET function:

add webhook:get_actions("test_webhook_get") = #"test_webhook_get";

3. Making Calls to Your Functions​

With your custom functions stored, they can now be called. Here's how you can do it using curl:

To call a POST function:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_JWT_TOKEN" -d '{"hej": "hopp"}' http://localhost:35021/sa/webhook/test_webhook

To call a GET function:

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" "http://localhost:35021/sa/webhook/test_webhook_get?A=hej&B=3"

Note: Replace YOUR_JWT_TOKEN with your actual JWT.

4. Verifying Your Functions​

You can verify the functionality of your webhook by checking the response.

For a POST function, the response should be:

"test_webhook OK!"

For a GET function, the response should be:

"hejhejhej"

In the case of any issues, the system will return an error message to aid debugging.

Configuring JWT Tokens for Webhook API​

For secure communication with the Webhook API, JWT tokens are used. Here's how you can configure them.

1. Updating the Secret Key​

Before generating a JWT (JSON Web Token), the secret key that will be used to sign the token needs to be set or updated. Use the webhook:update_secret function to set a new secret for the webhook endpoint.

Here's how to update the secret key:

webhook:update_secret("your_new_secret");

Replace "your_new_secret" with your own secret key.

If you're enabling webhooks on the running server for the first time, use the webhook:enable function with your secret as the argument:

webhook:enable("your_new_secret");

2. Generating JWT Tokens​

Once the secret key is set, you can generate a JWT using the webhook:create_token function. This function takes three parameters: a list of topics, a list of actions, and a valid time (in seconds).

Here's how to create a JWT token:

webhook:create_token(["*est*", "ost*", "bunker"], ["test_webhook", "gc*", "test_webhook_get"], 3600);

The first parameter is a vector of strings representing the topics this token is allowed to publish data on. The second parameter is a vector of strings representing the HTTP webhooks the bearer of the token is allowed to call. The third parameter is the time (in seconds) the token should be valid.

This example will generate a JWT that is valid for 1 hour and allows publishing data on topics that match any of the given patterns and calling any webhook that matches the given patterns.

Note that the JWTs can be generated by any system that knows the secret and the token has the right keys in it's payload.

Below is an example payload that would be generated by the call to webhook:create_token above:

{
  "tp": [
    "*est*",
    "ost*",
    "bunker"
  ],
  "ac": [
    "test_webhook",
    "gc*",
    "foo_test*"
  ],
  "iat": <seconds since epoch>,
  "exp": <seconds-since-epoch> + 3600
}

3. Using the JWT Token​

With your JWT token generated, it can now be used to authenticate your requests to the webhook API. In curl, you can provide the token as part of the Authorization header.

For a POST function:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_JWT_TOKEN" -d '{"hej": "hopp"}' http://localhost:35021/sa/webhook/test_webhook

For a GET function:

curl -X GET -H "Authorization: Bearer YOUR_JWT_TOKEN" "http://localhost:35021/sa/webhook/test_webhook_get?A=hej&B=3"

Replace YOUR_JWT_TOKEN with the token you have generated.

Keep your JWT secure and avoid sharing it publicly, as it is sensitive information.