Transformations
When you apply webhooks in IBM® Security Verify, it involves contacting remote systems, which are not always authored and deployed by the tenant administrator. Because these remote systems might expose rigid APIs, it might be necessary for the request or response payload of a webhook call to be mutated to achieve a functioning integration between Verify and the remote system.
To achieve this integration, webhooks expose a capability that is called transforms. Administrators can use this capability to author expressions that mutate the HTTP request and response.
A webhook transform is a CEL
expression, the output of which is a map that
contains well-known keys. These keys map to the portions that make up an HTTP request or response.
Each key in the transform output is optional and, if not provided, that portion of the request or
response won't be modified.
Outgoing Transforms
Outgoing transforms apply to the HTTP request before it is sent to the webhook destination.
Name | Type | Read only | Notes |
---|---|---|---|
body |
map[string]object |
N | |
header |
map[string]list[string] |
N | |
method |
string |
N | |
path |
string |
N | |
host |
string |
Y | Present only when the host is consistent across all configured URLs. |
CEL
specification.CEL
expression is a map that is declared with well-known keys as shown in
the following example.{
"body":body,
"header":header,
"path":path
}
Name | Type | Notes |
---|---|---|
body |
map[string]object or string |
|
header |
map[string]list[string] or map[string]string |
|
method |
string |
|
path |
string |
|
query |
map[string]string or map[string]list[string] |
|
skip_authentication |
boolean |
If set to true, the configured authentication mechanism is not used. Use this key for situations when the transform is adding the authorization details to the request. |
Incoming Transforms
Incoming transforms apply to the HTTP response as it is received from the webhook that was started.
Name | Type | Read only | Notes |
---|---|---|---|
body |
map[string]object |
N | |
header |
map[string]list[string] |
Y | |
status_code |
integer |
Y | |
request |
map[string]object |
Y | Contains the outgoing transform arguments. For example, request.body to
access the original request body. |
- Only the body of an incoming transform is modifiable. Changes to
header
orstatus_code
have no effect. - Incoming transforms are started only after the status code is validated. Ensure that the
expectedStatus
field of the webhook or resource is appropriately set.
Common bugs in transforms
- Number equalities failing
- When a comparison is performed on a number that comes out of the HTTP body, an equals check
might not work as expected on a number. The following code is an example of a payload, the
CEL
applied to it and the output.body argument value
:{ "value": 2 }
CEL
:{ "body" : body.put("gte": body.value >= 2) }
Result
:{ "value":2, "gte": false }
This result is because the
body.value
expression is yielding a decimal value. As JSON, numbers are by definition not integers. A cast corrects the behavior. See the following example.Incoming body
:{ "value": 2 }
CEL
:{ "body" : body.put("gte": int(body.value) >= 2) }
Result
:{ "value":2, "gte": true }
- Removing the body from a request
- Some APIs might require that all information be delivered in the URL and headers and that no
body be included in the request. For these APIs, a transform might be needed to remove the outgoing
HTTP body from the request. To remove the body from the out going request take the following actions.
- Set the content-type to an empty string.
- Set the HTTP body to an empty string.
The following example shows how to remove the body as part of an outgoing transform:
CEL:
{ "body":"", "header": header.put("content-type","") }