Webhook Custom Payloads

Which variables can I use for my Webhooks Custom Payload?

Engineering avatar
Written by Engineering
Updated over a week ago

Having defaults to get started quickly is nice, but at some point, you want to customize and configure a precise payload to send to your Webhook endpoint. A Custom Payload gives you the flexibility you need to integrate with any cloud service out there.

At the bottom of the Webhook Setup Form, if you have the Custom Payload selector enabled, there is a Custom Payload Template textarea available. By default, the template looks similar to this:

{
  "event": "{ /event }",
  "data": "{ /data }",
  "webhook": "{ /webhook }"


That might look a bit daunting at first, but it simply shows a JSON object with three properties: "event", "data" and "webhook". For the value part for each of these keys, you see something like "{ /something }". That is a variable (placeholder) using something called JSON Pointers. You don't need to read the specification to understand how they work. 

A JSON Pointer retrieves the value from an object using the given path.

If you have the following object:

{
  "path": {
    "to": {
      "something": "easy"
    }
  }
}

and the following payload with your absolute JSON Pointer:

{
  "text": "This is very { /path/to/something }."
}

It will produce:

{
  "text": "This is very easy."
}

The { /path/to/something } is replaced with the actual value ("easy" ) from the available object. 

The value does not need to be a string and can be a more complex structure like another object.

To get back to the default template set for your custom payload template:

{
  "event": "{ /event }",
  "data": "{ /data }",
  "webhook": "{ /webhook }"
}

With your newly gained knowledge regarding JSON Pointers, it is now clear that the values ({ /event }, { /data }, { /webhook }) will be replaced with the actual data it points to.

For each webhook request, Flamelink makes an object available with these three properties from which you can construct your custom payloads:

event:
This is an object that represents the event that took place for which the webhook request is triggered. The event object is the default payload for when you do not use the Custom Payload Template.

{
  id, // unique identifier for each event
  type, // type of event, e.g. "content.create"
  webhookId, // ID of associated webhook configuration
  projectId,  // Firebase project ID
  created, // seconds since Unix epoch
  livemode, // always "true" except when sending a test webhook
  url, // endpoint to which the request will be sent
  method, // HTTP method for request, e.g. POST, GET, etc
  data // the actual data object for the specific event, e.g. content entry that is updated
}

data:
This is the same as { /event/data }. It is the actual data for the specific event that took place. The structure of the data is 100% based on the type of event and how your content is structured.

webhook:
This is the webhook config object. If you want to include something from this config object itself in your payload, you can use this.

NOTE: Currently, there is a limit of 100KB on the size of your webhook payload.

Transformation Helpers:

Flamelink gives you a lot of transformation helper functions that you can optionally apply to any of the dynamic JSON Pointer variables. The syntax is straightforward. Add as many transformation functions as you want before the first forward-slash (/) separated by a comma. If a transformation helper function takes any arguments, separate them with a space.

Let's use our previous example with a transformation helper to uppercase the word "easy":

{
  "text": "This is very { upper-case /path/to/something }."
}

It will produce:

{
  "text": "This is very EASY."
}

Full list of transformation helpers:

json-stringify
Convert a JavaScript object or value into a JSON string.

{ json-stringify /data }

json-parse
Parse a JSON string, constructing the JavaScript value or object described by the string.

{ json-parse /data/some/object/string }

camel-case
Converts a string to camel case.

{ camel-case /data/some/title }

capitalize
Converts the first character of string to upper case and the remaining to lower case.

{ capitalize /data/some/title }

deburr
Deburrs a string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing combining diacritical marks.

{ deburr /data/some/title }

escape
Converts the characters "&", "<", ">", '"', and "'" in string to their corresponding HTML entities.

{ escape /data/some/title }

kebab-case
Converts string to kebab case.

{ kebab-case /data/some/title }

lower-case
Converts string, as space separated words, to lower case.

{ lower-case /data/some/title }

lower-first
Converts the first character of string to lower case.

{ lower-first /data/some/title }

pad
Pads a string on the left and right sides if it's shorter than a given length. Padding characters are truncated if they can't be evenly divided by the length.

{ pad 10 /data/some/title }
// pad title to be 10 characters using spaces
{ pad 10 * /data/some/title }
// pad title to be 10 characters using asterisk (*) characters

pad-end
Pads string on the right side if it's shorter than length. Padding characters are truncated if they exceed length.

{ pad-end 20 # /data/some/title }
// pad title to 20 characters using # characters at the end

pad-start
Pads string on the left side if it's shorter than length. Padding characters are truncated if they exceed length.

{ pad-start 20 # /data/some/title }
// pad title to 20 characters using # characters at the beginning

parse-integer
Converts a string to an integer of the specified radix. If no radix is provided it will default to 10 unless the value is a hexadecimal, in which case the radix will be 16.

{ parse-integer 10 /data/some/string }

repeat
Repeats the given string n times.

{ repeat 5 /data/some/string }

replace
Replaces matches for a given string with a replacement string within the value.

{ replace old new /data/some/string }

snake-case
Converts a string to snake case.

{ snake-case /data/some/string }

split
Splits a string by a given separator. Optionally specify a limit number as second argument to only retrieve that number of items in the returned array.

{ split * 3 /data/some/string }

start-case
Converts a string to start case.

{ start-case /data/some/string }

to-lower
Converts a string, as a whole, to lower case just like String#toLowerCase.

{ to-lower /data/some/string }

to-upper
Converts a string, as a whole, to upper case just like String#toUpperCase.

{ to-upper /data/some/string }

trim
Removes leading and trailing whitespace or specified characters from string.

trim-end
Removes trailing whitespace or specified characters from string.

trim-start
Removes leading whitespace or specified characters from string.

truncate
Truncates string if it's longer than the given maximum string length. The last characters of the truncated string are replaced with the omission string which defaults to "...".

unescape
The inverse of _.escape; this method converts the HTML entities &amp;, &lt;, &gt;, &quot;, and &#39; in string to their corresponding characters.

upper-case
Converts string, as space separated words, to upper case.

upper-first
Converts the first character of string to upper case.

words
Splits string into an array of its words.

first-char
Returns the first n  number of characters from the string.

first-word
Returns the first n  number of words from the string. Words are split using spaces.

first-paragraph
Returns the first n  number of paragraphs from the string. Paragraphs are split using line breaks.

last-char
Returns the last n  number of characters from the string.

last-word
Returns the last n  number of words from the string. Words are split using spaces.

last-paragraph
Returns the last n  number of paragraphs from the string. Paragraphs are split using line breaks.

markdown-to-html
Converts any markdown in a string to HTML tags.

html-to-markdown
Converts any HTML tags in a string into Markdown.

strip-white-space
Removes all white space from a string.

strip-markdown
Strip any Markdown formatting that is not plain text from a string.

strip-html
Strips all HTML tags from a string. Optionally specify a list of allowed tags not to strip as well as a replacement tag if needed.

strip-stop-words
Strip any stop words from a string.

Examples:

Slack Notification

Slack expects any incoming notifications to have a specific payload.

{ 
  "text": "The `{ to-upper /data/title }` schema was { last-char 6 /event/type }d!",
  "channel": "general",
  "icon_emoji": ":trophy:"
}

Assuming I have a trigger set up for "create", "update" and "delete" for "Schemas", and a "Products" schema, this will send a Slack notification to the "general" channel that looks something like this:

🏆 The Products schema was updated!

You can get more creative than this, but it gives you an idea of what is possible.

Did this answer your question?