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.

The following table shows the outgoing transform input arguments.
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.
These parameters can be referenced according to the CEL specification.
The CEL expression is a map that is declared with well-known keys as shown in the following example.
{
  "body":body,
  "header":header,
  "path":path   
}
Note: It is not necessary to include keys when changes are not being made. The preceding example is just to illustrate the map format.
The following table shows the outgoing transform keys.
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.

The following table shows the incoming transform input arguments.
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.
Note:
  • Only the body of an incoming transform is modifiable. Changes to header or status_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

You might encounter similar common issues.
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","")
}