Creating custom webhook templates

As outlined in Creating webhooks, you can specify custom webhook templates to tailor the fields and text contained in payloads.

The following supplementary information is provided to help you configure payload templates that produce valid output.

As described in Creating webhooks, you must include a compatible Content-Type header (at step h) when providing a custom webhook template.

Field references

When creating a custom webhook template, only the fields you include will be sent in payloads. This section describes how to reference event fields based on their type. For a full list of fields that can be referenced, see the Custom field column in the tables documented in Webhook payload fields.

In some of the following examples, functions are used. Refer to the section below for explanations about them.

• Regular fields: Regular fields are those that are not nested. To reference a regular field, enclose the field in double curly brackets.
  

  For example, {{.TenantUuid}} references the .TenantUuid field for an audit log event.

• Nested fields of an object: Nested fields of an object are indented below a field marked with a * in the Custom field column. In the nested field's Type column, the text ...nested in object... is included. To reference a nested field of an object, enclose both fields in double curly brackets with the object field preceding.

  For example, {{.Metadata.FileName}} references the .Filename field, which is nested in the .Metadata object in a detection event.

• Nested fields of an array: Nested fields of an array are indented below a field marked with a * in the Custom field column. In the nested field's Type column, the text ...nested in array... is included. To reference a nested field of an array, use the structure in the following example. Also see Functions below to learn about the built-in array function.
  

  For example, {{ array .ProcessInfo {{.BinaryName}} }} references the .BinaryName field, which is nested in the .ProcessInfo array in a detection event.

• Keys of map fields: Map fields contain one or more key:value pairs and are indicated by the text Map in the Type column for a field. To reference a key in a map field, enclose the map field and key in double curly brackets with the map field preceding.
  

  For example, {{.Fields.summary}} references the summary key in the .Fields map in an audit log event.

You can use a single period to reference an entire object or value depending on the context.

For example: To reference an entire event object, wrap it, and assign it a key, you could use {"event":{{json .}}} as your template. To reference and assign a key to a value in the .Tags array, you could use {{ array .Tags {"tag_name":{{ json . }}} }} in your template.

If a webhook only accepts JSON payloads, the escape or json function should be used with fields in most cases to ensure the template produces valid output, as described below.

Functions

We provide the following built-in functions to either help you to ensure payloads will be formatted correctly if your webhook only accepts JSON, or to ease accessing values in an array.

• escape: A function that inserts a backslash before special JSON characters in a string so that they are treated as literal characters.
  

  You can ensure that node hostnames are displayed correctly. For example: Template:"Detection generated by {{escape .AgentHostname}}." Payload output: "Detection generated by ben-laptop."

• json: A function that converts arrays, timestamps, and any other data type into JSON format.
  

  When used with an array of strings, values will be escaped, separated by commas, and enclosed by speech marks. For example: Template:{{json .Tags}} Payload output:["fileopen","cyberhygiene","fileaccess"]

• array: A function that creates a new array from an array field and formats it as JSON. This is useful for an array of objects (e.g. .ProcessInfo) because you can gather a specific field's values from each of the objects. You can also use this function to format each value in an array.

If an event comprises multiple processes, the event data will contain multiple process information (.ProcessInfo) objects. To gather the .BinaryName field values from each object, you can do the following: Template:{{ array .ProcessInfo {{json .BinaryName}}}} Payload output: ["explorer.exe","chrome.exe"] To format each value in the .Tags array, you can do the following: Template: {{ array .Tags {"tag_name":{{ json . }}} }} Payload output: [{"tag_name":"cyberhygiene"},{"tag_name":"fileopen"}]

Full template example

The following custom template is intended for Jira, and is constructed so that each time the webhook receives a batch of audit log events, an issue is created. A batch of events consists of an array of event objects, as described in the Batched events table in Webhook payload fields.

{
  "fields": {
    "project": {
      "id": "10000"
    },
    "issuetype": {
      "id": "10001"
    },
    "summary": "New Audit Log events",
    "description": {
      "version": 1,
      "type": "doc",
      "content": [
        {
          "type": "bulletList",
          "content": {{ array .AuditLogs
            {
              "type": "listItem",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": {{ json .Fields.summary }},
                      "marks": [
                        {
                          "type": "strong"
                        }
                      ]
                    }
                  ]
                },
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Timestamp: ",
                      "marks": [
                        {
                          "type": "strong"
                        }
                      ]
                    },
                    {
                      "type": "text",
                      "text": {{ json .Fields.timestamp }}
                    }
                  ]
                },
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Operator: ",
                      "marks": [
                        {
                          "type": "strong"
                        }
                      ]
                    },
                    {
                      "type": "text",
                      "text": {{ json .Fields.auth.operator_display_name }}
                    }
                  ]
                },
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Event type: {{ escape .Type }}"
                    }
                  ]
                }
              ]
            }
          }}
        }
      ]
    }
  }
}