1Kosmos · Webhooks

Webhooks API

Deliver signed platform-event callbacks to your endpoints.

The Webhooks service delivers platform events to your own endpoints. Register subscriptions, choose the events you care about, and receive signed callbacks when they happen.

12 endpoints

across 8 resource groups.

ECDSA-signed

every request is signed with your key pair.

JSON over HTTPS

predictable REST, conventional status codes.

OpenAPI 3.0

Download the spec →

Reference

Base URL

All Webhooks endpoints are relative to your environment host. Examples on this page use the 1Kosmos pilot environment — swap in your production root when you go live.

Pilot

Content type

Requests and responses use application/json.

GET/healthz

curl -X GET '/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

Security

Authentication

Webhooks uses ECDSA key-pair authentication. Each request carries your credentials as HTTP headers; verification-grade calls additionally sign the request body. Retrieve the system signing key from /publickeys.

Credentials

keyIdECDSA Public Keyheader

keySecretECDSA Private Keyheader

licenseLicense key from License Microserviceheader

GET/healthz

cURL

Node.js

Python

curl -X GET '/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/healthz", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

Reference

Errors

Webhooks uses conventional HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a service-side error.

Status	Meaning	Description
200 / 204	OK	The request succeeded.
400	Bad Request	Validation failed.
401	Unauthorized	Missing or invalid credentials.
403	Forbidden	Authenticated, but not permitted.
404	Not Found	The resource does not exist.
500	Server Error	Something went wrong on our side.

4XXerror response

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error"
}

Webhooks

POST/tenant/{tenantId}/community/{communityId}/webhooks/fetch

Fetch webhooks.

A valid community license key with auth level system / service or / service_ext is required
If the system key is used to fetch webhooks, then only webhooks have the credential object.
If another key is used to fetch webhooks, the API does not provide a credential object.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

pIndex (optional)

The pIndex key is a cursor for the pagination.

pSize (optional)

A limit on the number of objects to be returned. The range between 1 to 100 and the default is 25.

tags (optional)

The tags key will use to filter the webhooks

Returns

Returns the fetched webhook data.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
tenantIdrequired	string	ID of tenant
communityIdrequired	string	ID of community

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

Request body contains below fields to fetch webhook.

Field	Type	Description
pIndex	number	—
pSize	number	—
tags	array<string>	—

POST/tenant/{tenantId}/community/{communityId}/webhooks/fetch

cURL

Node.js

Python

curl -X POST '/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhooks/fetch' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"pIndex": 0, "pSize": 25, "tags": ["string"]}'

const res = await fetch("/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhooks/fetch", {
  method: "POST",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "pIndex": 0,
    "pSize": 25,
    "tags": [
      "string"
    ]
  })
});
const data = await res.json();

import requests

res = requests.post(
    "/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhooks/fetch",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "pIndex": 0,
      "pSize": 25,
      "tags": [
        "string"
      ]
    },
)
print(res.json())

RESPONSE

200

400

401

405

Success Webhooks fetch result with pagination details. ``` { "page": { "index": 0, page number, starting from 0 "total": 50, total number of records "size": 25 number of records, per page }, "data": [ { "_id": "xxxxxxxxxxxxxxx", "tenantId": "xxxx", "communityId": "xxxx", "eventNames": ["xxxx"], "tags": ["xxxxx"], "name": "xxxx", "disabled": false, "createdBy": "xxxx", "query": [ { "key1": "xxxx" } ], "criteria": "ANY", "api": { "type": "POST", "url": "https://xxx.xxxxxx.xxx/xxxxx", "authType": "none", "oAuthGrantType": "client_credentials", "oAuthTokenUrl": "xxxxx", "oAuthScopes": [], "credential": { "username": "xxxx", "password": "xxxx", "keyName": "xxxx", "keyValue": "xxxx", "token": "xxxx", "oauth2": { "clientId": "xxxx", "clientSecret": "xxxx" } } }, "successCodes": [ 200 ], "retryCodes": [ 0 ], "retryCount": 0, "ttl": 0 } ], "publicKey": "servicekey's publickey" } ```

{
  "page": {
    "index": 0,
    "total": 0,
    "size": 0
  },
  "data": [
    {
      "_id": "xxxxxxxxxxxxxxx",
      "tenantId": "xxxx",
      "communityId": "xxxx",
      "eventNames": [
        "xxxx"
      ],
      "name": "xxxx",
      "disabled": false,
      "createdBy": "xxxx",
      "tags": [
        "log_stream"
      ],
      "query": [
        {
          "key1": "xxxx"
        }
      ],
      "criteria": "ANY",
      "api": {
        "type": "POST",
        "url": "https://xxx.xxxxxx.xxx/xxxxx",
        "authType": "none",
        "oAuthGrantType": "client_credentials",
        "oAuthTokenUrl": "xxxx",
        "oAuthScopes": [
          "xxxx"
        ],
        "credential": {
          "username": "xxxx",
          "password": "xxxx",
          "keyName": "xxxx",
          "keyValue": "xxxx",
          "token": "xxxx",
          "oauth2": {
            "clientId": "xxxx",
            "clientSecret": "xxxx"
          }
        }
      },
      "successCodes": [
        200
      ],
      "retryCodes": [
        0
      ],
      "retryCount": 0,
      "ttl": 0
    }
  ]
}

// no response body

// no response body

// no response body

PUT/tenant/{tenantId}/community/{communityId}/webhook

Create webhook.

A valid community license key with auth level system / service or / service_ext is required

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

eventNames (required)

This key sets the event names for webhook.

name (required)

This key sets the name for the webhook.

disabled (required)

This key set disabled status of a webhook.

createdBy (required)

This key sets the created by for the webhook.

tags (optional)

The tags key will use to filter the webhooks

query (optional)

The query to filter webhooks.

criteria (optional)

This key sets the status of a webhook. The type key only accept these values ("ALL", "ANY").

api (required)

This key sets the API details of a webhook.

successCodes (required)

This key sets the success codes of a API.

retryCodes (optional)

This key sets the retry codes of a API.

retryCount (optional)

This key sets the retry count of API calles. min = 0, max 2

ttl (optional)

This key sets the ttl of API response. min = 0, max 5

Returns

Returns the created webhook data.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
tenantIdrequired	string	ID of tenant
communityIdrequired	string	ID of community

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

Request body contains below fields to create webhook.

  {
      "eventName": "xxxx",
      "name": "xxxx",
      "disabled": false,
      "createdBy": "xxxx",
      "query": [
         {
          "key1": "xxxx"
         }
       ],
       "criteria": "ANY/ALL",
       "api": {
         "type": "POST",
         "url": "https://xxx.xxxxxx.xxx/xxxxx",
         "authType": "none", // Valid auth types [ none, basic, bearer, api_key, oauth2]
         "oAuthGrantType": "client_credentials", // required for authType = oauth2
         "oAuthTokenUrl": "xxxxx", Token URL for OAuth2, required for authType = oauth2
         "oAuthScopes": [], // Array of OAuth2 scopes, optional
         "credential": {
           "username": "xxxx", // This should be plain text
           "password": "xxxx", // This should be plain text
           "keyName": "xxxx", // This should be plain text
           "keyValue": "xxxx", // This should be plain text
           "token": "xxxx" // This should be plain text
           "oauth2": {
              "clientId": "xxxx", // Client ID for OAuth2
              "clientSecret": "xxxx", // Client Secret for OAuth2
            }
          }
        },
       "successCodes": [
           200
       ],
       "retryCodes": [
          0
       ],
      "retryCount": 0,
      "ttl": 0
  }

Field	Type	Description
eventNamesrequired	array<string>	—
namerequired	string	—
disabled	boolean	—
createdBy	string	—
tags	array<string>	—
query	array<object>	—
criteria	string	—
apirequired	object	—
successCodesrequired	array<number>	—
retryCodes	array<number>	—
retryCount	number	—
ttl	number	—

PUT/tenant/{tenantId}/community/{communityId}/webhook

cURL

Node.js

Python

curl -X PUT '/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhook' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"eventNames": ["xxxx"], "name": "xxxx", "disabled": false, "createdBy": "xxxx", "tags": ["log_stream"], "query": [{"key1": "xxxx"}], "criteria": "ANY", "api": {"type": "POST", "url": "https://xxx.xxxxxx.xxx/xxxxx", "authType": "none", "oAuthGrantType": "client_credentials", "oAuthTokenUrl": "xxxx", "oAuthScopes": ["xxxx"], "credential": {"username": "xxxx", "password": "xxxx", "keyName": "xxxx", "keyValue": "xxxx", "token": "xxxx", "oauth2": {"clientId": "xxxx", "clientSecret": "xxxx"}}}, "successCodes": [200], "retryCodes": [0], "retryCount": 0, "ttl": 0}'

const res = await fetch("/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhook", {
  method: "PUT",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "eventNames": [
      "xxxx"
    ],
    "name": "xxxx",
    "disabled": false,
    "createdBy": "xxxx",
    "tags": [
      "log_stream"
    ],
    "query": [
      {
        "key1": "xxxx"
      }
    ],
    "criteria": "ANY",
    "api": {
      "type": "POST",
      "url": "https://xxx.xxxxxx.xxx/xxxxx",
      "authType": "none",
      "oAuthGrantType": "client_credentials",
      "oAuthTokenUrl": "xxxx",
      "oAuthScopes": [
        "xxxx"
      ],
      "credential": {
        "username": "xxxx",
        "password": "xxxx",
        "keyName": "xxxx",
        "keyValue": "xxxx",
        "token": "xxxx",
        "oauth2": {
          "clientId": "xxxx",
          "clientSecret": "xxxx"
        }
      }
    },
    "successCodes": [
      200
    ],
    "retryCodes": [
      0
    ],
    "retryCount": 0,
    "ttl": 0
  })
});
const data = await res.json();

import requests

res = requests.put(
    "/tenant/xxxxxxxxxxxx/community/xxxxxxxxxxxx/webhook",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "eventNames": [
        "xxxx"
      ],
      "name": "xxxx",
      "disabled": false,
      "createdBy": "xxxx",
      "tags": [
        "log_stream"
      ],
      "query": [
        {
          "key1": "xxxx"
        }
      ],
      "criteria": "ANY",
      "api": {
        "type": "POST",
        "url": "https://xxx.xxxxxx.xxx/xxxxx",
        "authType": "none",
        "oAuthGrantType": "client_credentials",
        "oAuthTokenUrl": "xxxx",
        "oAuthScopes": [
          "xxxx"
        ],
        "credential": {
          "username": "xxxx",
          "password": "xxxx",
          "keyName": "xxxx",
          "keyValue": "xxxx",
          "token": "xxxx",
          "oauth2": {
            "clientId": "xxxx",
            "clientSecret": "xxxx"
          }
        }
      },
      "successCodes": [
        200
      ],
      "retryCodes": [
        0
      ],
      "retryCount": 0,
      "ttl": 0
    },
)
print(res.json())

RESPONSE

200

400

401

405

Success

{
  "_id": "xxxxxxxxxxxxxxx",
  "tenantId": "xxxx",
  "communityId": "xxxx",
  "eventNames": [
    "xxxx"
  ],
  "name": "xxxx",
  "disabled": false,
  "createdBy": "xxxx",
  "tags": [
    "log_stream"
  ],
  "query": [
    {
      "key1": "xxxx"
    }
  ],
  "criteria": "ANY",
  "api": {
    "type": "POST",
    "url": "https://xxx.xxxxxx.xxx/xxxxx",
    "authType": "none",
    "oAuthGrantType": "client_credentials",
    "oAuthTokenUrl": "xxxx",
    "oAuthScopes": [
      "xxxx"
    ],
    "credential": {
      "username": "xxxx",
      "password": "xxxx",
      "keyName": "xxxx",
      "keyValue": "xxxx",
      "token": "xxxx",
      "oauth2": {
        "clientId": "xxxx",
        "clientSecret": "xxxx"
      }
    }
  },
  "successCodes": [
    200
  ],
  "retryCodes": [
    0
  ],
  "retryCount": 0,
  "ttl": 0
}

// no response body

// no response body

// no response body

PATCH/tenant/{tenantId}/community/{communityId}/webhook/{webhookId}

Update webhook.

A valid community license key with auth level system / service or / service_ext is required

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Request Body

name (required)

This key sets the name for the webhook.

disabled (required)

This key set disabled status of a webhook.

eventNames (required)

This key sets the event names for webhook.

query (optional)

The query to filter webhooks.

criteria (optional)

This key sets the status of a webhook. The type key only accept these values ("ALL", "ANY").

api (required)

This key sets the API details of a webhook.

successCodes (required)

This key sets the success codes of a API.

retryCodes (optional)

This key sets the retry codes of a API.

retryCount (optional)

This key sets the retry count of API calles. min = 0, max 2

ttl (optional)

This key sets the ttl of API response. min = 0, max 5

Returns

Returns the created webhook data.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
tenantIdrequired	string	ID of tenant
communityIdrequired	string	ID of community
webhookIdrequired	string	ID of webhook

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

Request body

Request body contains below fields to update webhook.

  {
      "name": "xxxx",
      "disabled": false,
      "eventNames": ['E_IDV_DOCUMENT_VALIDATE'],
      "query": [
         {
          "key1": "xxxx"
         }
       ],
       "criteria": "ANY/ALL",
       "api": {
         "type": "POST",
         "url": "https://xxx.xxxxxx.xxx/xxxxx",
         "authType": "none", // Valid auth types [ none, basic, bearer, api_key, oauth2]
         "oAuthGrantType": "client_credentials", // required for authType = oauth2
         "oAuthTokenUrl": "xxxxx", Token URL for OAuth2, required for authType = oauth2
         "oAuthScopes": [], // Array of OAuth2 scopes, optional
         "credential": {
           "username": "xxxx", // This should be plain text
           "password": "xxxx", // This should be plain text
           "keyName": "xxxx", // This should be plain text
           "keyValue": "xxxx", // This should be plain text
           "token": "xxxx" // This should be plain text
           "oauth2": {
              "clientId": "xxxx", // Client ID for OAuth2
              "clientSecret": "xxxx", // Client Secret for OAuth2
            }
          }
        },
       "successCodes": [
           200
       ],
       "retryCodes": [
          0
       ],
      "retryCount": 0,
      "ttl": 0
  }

Field	Type	Description
name	string	—
disabled	boolean	—
eventNames	array<string>	—
query	array<object>	—
criteria	string	—
api	object	—
successCodes	array<number>	—
retryCodes	array<number>	—
retryCount	number	—
ttl	number	—

PATCH/tenant/{tenantId}/community/{communityId}/webhook/{webhookId}

cURL

Node.js

Python

curl -X PATCH '/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "xxxx", "disabled": false, "eventNames": ["xxxx"], "query": [{"key1": "xxxx"}], "criteria": "ANY", "api": {"type": "POST", "url": "https://xxx.xxxxxx.xxx/xxxxx", "authType": "none", "oAuthGrantType": "client_credentials", "oAuthTokenUrl": "xxxx", "oAuthScopes": ["xxxx"], "credential": {"username": "xxxx", "password": "xxxx", "keyName": "xxxx", "keyValue": "xxxx", "token": "xxxx", "oauth2": {"clientId": "xxxx", "clientSecret": "xxxx"}}}, "successCodes": [200], "retryCodes": [0], "retryCount": 0, "ttl": 0}'

const res = await fetch("/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx", {
  method: "PATCH",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "xxxx",
    "disabled": false,
    "eventNames": [
      "xxxx"
    ],
    "query": [
      {
        "key1": "xxxx"
      }
    ],
    "criteria": "ANY",
    "api": {
      "type": "POST",
      "url": "https://xxx.xxxxxx.xxx/xxxxx",
      "authType": "none",
      "oAuthGrantType": "client_credentials",
      "oAuthTokenUrl": "xxxx",
      "oAuthScopes": [
        "xxxx"
      ],
      "credential": {
        "username": "xxxx",
        "password": "xxxx",
        "keyName": "xxxx",
        "keyValue": "xxxx",
        "token": "xxxx",
        "oauth2": {
          "clientId": "xxxx",
          "clientSecret": "xxxx"
        }
      }
    },
    "successCodes": [
      200
    ],
    "retryCodes": [
      0
    ],
    "retryCount": 0,
    "ttl": 0
  })
});
const data = await res.json();

import requests

res = requests.patch(
    "/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "name": "xxxx",
      "disabled": false,
      "eventNames": [
        "xxxx"
      ],
      "query": [
        {
          "key1": "xxxx"
        }
      ],
      "criteria": "ANY",
      "api": {
        "type": "POST",
        "url": "https://xxx.xxxxxx.xxx/xxxxx",
        "authType": "none",
        "oAuthGrantType": "client_credentials",
        "oAuthTokenUrl": "xxxx",
        "oAuthScopes": [
          "xxxx"
        ],
        "credential": {
          "username": "xxxx",
          "password": "xxxx",
          "keyName": "xxxx",
          "keyValue": "xxxx",
          "token": "xxxx",
          "oauth2": {
            "clientId": "xxxx",
            "clientSecret": "xxxx"
          }
        }
      },
      "successCodes": [
        200
      ],
      "retryCodes": [
        0
      ],
      "retryCount": 0,
      "ttl": 0
    },
)
print(res.json())

RESPONSE

200

400

401

405

Success

{
  "_id": "xxxxxxxxxxxxxxx",
  "tenantId": "xxxx",
  "communityId": "xxxx",
  "eventNames": [
    "xxxx"
  ],
  "name": "xxxx",
  "disabled": false,
  "createdBy": "xxxx",
  "tags": [
    "log_stream"
  ],
  "query": [
    {
      "key1": "xxxx"
    }
  ],
  "criteria": "ANY",
  "api": {
    "type": "POST",
    "url": "https://xxx.xxxxxx.xxx/xxxxx",
    "authType": "none",
    "oAuthGrantType": "client_credentials",
    "oAuthTokenUrl": "xxxx",
    "oAuthScopes": [
      "xxxx"
    ],
    "credential": {
      "username": "xxxx",
      "password": "xxxx",
      "keyName": "xxxx",
      "keyValue": "xxxx",
      "token": "xxxx",
      "oauth2": {
        "clientId": "xxxx",
        "clientSecret": "xxxx"
      }
    }
  },
  "successCodes": [
    200
  ],
  "retryCodes": [
    0
  ],
  "retryCount": 0,
  "ttl": 0
}

// no response body

// no response body

// no response body

DELETE/tenant/{tenantId}/community/{communityId}/webhook/{webhookId}

Delete webhook.

A valid community license key with auth level system / service or / service_ext is required

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns no content.

This API throw an error if something goes wrong.

Path parameters

Name	Type	Description
tenantIdrequired	string	ID of tenant
communityIdrequired	string	ID of community
webhookIdrequired	string	ID of webhook

Headers

Name	Type	Description
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒

DELETE/tenant/{tenantId}/community/{communityId}/webhook/{webhookId}

cURL

Node.js

Python

curl -X DELETE '/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx", {
  method: "DELETE",
  headers: {
    "licensekey": "YOUR_LICENSE_KEY",
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "/tenant/xxxxxxxxxxxxxx/community/xxxxxxxxxxxxxx/webhook/xxxxxxxxxxxxxx",
    headers={
        "licensekey": "YOUR_LICENSE_KEY",
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

204

400

401

405

Success

// no response body

// no response body

// no response body

// no response body

Webhooks

Service Key

Service Key endpoints.

GET/servicekeys

Get service keys

This endpoint returns available service keys. The license you are using must be of authLevel 'system'

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns array with service keys

Headers

Name	Type	Description
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒

GET/servicekeys

cURL

Node.js

Python

curl -X GET '/servicekeys' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/servicekeys", {
  method: "GET",
  headers: {
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "licensekey": "YOUR_LICENSE_KEY",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/servicekeys",
    headers={
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "licensekey": "YOUR_LICENSE_KEY",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

403

500

Success

[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]

// no response body

// no response body

// no response body

// no response body

DELETE/servicekey/{keyId}

Reset Service Key

This endpoint resets service key for given keyId. Deletes current one and recreates a new one. The license you are using must be of authLevel 'system'

Parameters

keyId (required)

The keyId of service key to reset

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

publickey (required)

Public key

Returns

Returns re-created service key

Path parameters

Name	Type	Description
keyIdrequired	string	keyId of service key to reset

Headers

Name	Type	Description
requestidrequired	string	JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize 🔒
publickeyrequired	string	Public Key / Try Authorize 🔒
licensekeyrequired	string	License key encrypted with ECDSA / Try Authorize 🔒

DELETE/servicekey/{keyId}

cURL

Node.js

Python

curl -X DELETE '/servicekey/<keyId>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/servicekey/<keyId>", {
  method: "DELETE",
  headers: {
    "requestid": "<ecdsa-requestid>",
    "publickey": "<public-key>",
    "licensekey": "YOUR_LICENSE_KEY",
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.delete(
    "/servicekey/<keyId>",
    headers={
        "requestid": "<ecdsa-requestid>",
        "publickey": "<public-key>",
        "licensekey": "YOUR_LICENSE_KEY",
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

400

401

500

Success

[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]

// no response body

// no response body

// no response body

Webhooks

ECDSA Helper

ECDSA Helper endpoints.

POST/ecdsa_helper/{method}

Encrypt and decrypt the data string by public key and private key.

Parameters

method (optional)

The method parameter is type of enum. Default value is encrypt.

This parameter only accepts following values

encrypt, decrypt

Request Body

data (optional)

The data key is type of String.

publicKey (required)

The publicKey is type of string.

privateKey (required)

The privateKey is type of string.

Returns

Returns the encrypted/decrypted string.

This API throw an error if something goes wrong. A common source of error is public or private key is not valid.

Path parameters

Name	Type	Description
method	string	—

Request body

Field	Type	Description
data	string	—
publicKey	string	—
privateKey	string	—

POST/ecdsa_helper/{method}

cURL

Node.js

Python

curl -X POST '/ecdsa_helper/<method>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": "Hey, This is example data string.", "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=", "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="}'

const res = await fetch("/ecdsa_helper/<method>", {
  method: "POST",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "data": "Hey, This is example data string.",
    "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
    "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
  })
});
const data = await res.json();

import requests

res = requests.post(
    "/ecdsa_helper/<method>",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    },
    json={
      "data": "Hey, This is example data string.",
      "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
      "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="
    },
)
print(res.json())

RESPONSE

200

successful operation

{
  "data": "xxxxxxxxxxxxxxxxxxxx",
  "publicKey": "xxxxxxxxxxxxxxxxxxxx"
}

Webhooks

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

GET/environment

cURL

Node.js

Python

curl -X GET '/environment' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/environment", {
  method: "GET",
  headers: {
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/environment",
    headers={
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success

// no response body

Webhooks

Healthz

Healthz endpoints.

GET/healthz

Get healthz.

Get healthz

Returns

Returns a healthz object

``version = <git-tag>.<commit-id>.<dob>``

``git-tag``: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.
``commit-id``: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.
``dob``: Date Of Build. This is epoc-time-in-se conds that tell the time when the build was created.
if the code is not built from a git-tag, then the ``version =<commit-id>.<dob>``

GET/healthz

cURL

Node.js

Python

curl -X GET '/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/healthz", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/healthz",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success ``` { "status": "all services operational", "publicKey": "string" //same as <service>/publickeys endpoint, "code": "200", "version": "<version>" //as defined above } ```

{
  "status": "all services operational",
  "publicKey": "//same as <service>/publickeys endpoint",
  "code": "200",
  "version": "xxxx.xxxx.xxxx"
}

Webhooks

Public Key

Public Key endpoints.

GET/publickeys

Get system's public key.

Returns

Returns a public key object

GET/publickeys

cURL

Node.js

Python

curl -X GET '/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/publickeys", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/publickeys",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

401

{
  "publicKey": ""
}

// no response body

Webhooks

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Returns

Returns all service directories.

GET/sd

cURL

Node.js

Python

curl -X GET '/sd' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/sd", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/sd",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}

Webhooks

Well Known config

Well Known config endpoints.

GET/.well-known

Get well known config.

Get well known config

Returns

Returns an object

GET/.well-known

cURL

Node.js

Python

curl -X GET '/.well-known' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'

const res = await fetch("/.well-known", {
  method: "GET",
  headers: {
    "keyId": "YOUR_KEY_ID",
    "keySecret": "YOUR_KEY_SECRET",
    "license": "YOUR_LICENSE_KEY"
  }
});
const data = await res.json();

import requests

res = requests.get(
    "/.well-known",
    headers={
        "keyId": "YOUR_KEY_ID",
        "keySecret": "YOUR_KEY_SECRET",
        "license": "YOUR_LICENSE_KEY"
    }
)
print(res.json())

RESPONSE

200

Success ``` { "public_key": "string" //same as <service>/publickeys endpoint, } ```

{
  "public_key": "//same as <service>/publickeys endpoint"
}