Configuration (REST)

To set up the webhook for a REST service (HTTP + JSON), you must set the value of BusinessLogicWebhookType to “REST”. Additional settings must be set in a JSON object in the configuration BusinessLogicWebhookConfig, as detailed below.

The webhook service must run on port 443 and require TLS client connections. We may support additional ports in the future.

Example:

{
  "host": "some.hostname",
  "port": 443,
  "path": "/event"
}

Here is the JSON Schema that’s expected for the REST webhook configuration:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["host", "port", "path"],
  "properties": {
    "host": {
      "type": "string"
    },
    "port": {
      "type": "integer"
    },
    "path": {
      "type": "string"
    },
    "generateJwtHeader": {
      "type": "boolean"
    },
    "timeoutMs": {
      "type": "integer",
      "minimum": 100
    },
    "callStartTimeoutMs": {
      "type": "integer",
      "minimum": 100
    },
    "maxAttempts": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    },
    "trustedCACerts": {
      "type": "array",
      "items": {
        "type": "string",
        "contentMediaType": "application/x-x509-ca-cert",
        "contentEncoding": "base64"
      }
    },
    "clientCerts": {
      "type": "array",
      "items": {
        "type": "string",
        "contentMediaType": "application/x-x509-ca-cert",
        "contentEncoding": "base64"
      }
    },
    "httpHeaders": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "value": {
            "type": "string"
          },
          "sessionVariableKey": {
            "type": "string"
          }
        }
      }
    },
    "oauth2": {
      "type": "object",
      "required": ["tokenEndpoint", "scopes"],
      "properties": {
        "tokenEndpoint": {
          "type": "string",
          "format": "uri"
        },
        "refreshEndpoint": {
          "type": "string",
          "format": "uri"
        },
        "clientId": {
          "type": "string"
        },
        "clientSecret": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          }
        },
        "clientAuthType": {
          "type": "string",
          "default": "basic",
          "enum": ["basic", "post", "jwt", "jwtValue"]
        },
        "customParams": {
          "type": "object",
          "additionalProperties": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "string"
                }
              }
            ]
          }
        },
        "jwtValue": {
          "type": "string"
        },
        "jwt": {
          "type": "object",
          "required": ["issuer", "audience", "subject", "key", "algorithm", "expirationMs"],
          "properties": {
            "type": {
              "type": "string",
              "examples": ["JWT"]
            },
            "algorithm": {
              "type": "string",
              "enum": ["RS256"]
            },
            "audience": {
              "type": "string"
            },
            "issuer": {
              "type": "string"
            },
            "subject": {
              "type": "string"
            },
            "keyId": {
              "type": "string"
            },
            "jwtTokenId": {
              "type": "string"
            },
            "expirationMs": {
              "type": "integer",
              "minimum": 1
            },
            "key": {
              "type": "string",
              "contentMediaType": "application/pkcs8",
              "contentEncoding": "base64"
            },
            "certificates": {
              "type": "array",
              "items": {
                "type": "string",
                "contentMediaType": "application/x-x509-ca-cert",
                "contentEncoding": "base64"
              }
            },
            "other": {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}

Each property is the same as for the gRPC configuration described above, with the following additions:

  • path: The path of the HTTP URL. Must start with a slash “/”.
  • httpHeaders: Additional HTTP headers to send on each request. See HTTP headers.