Recipes: API and Libraries



API

An easy to use API has been built into the recipes system to allow you to quickly and easily write scripts to manipulate your webhook payloads.

Message Helper Functions

message.clearHeaderParams(); - Removes all the header params from the message.

message.hasHeaderParam(name); - Checks for the existance of a variable in the header. Returns true/false based on the check.

message.getHeaderParam(name); - Returns the value of the header variable.

message.addHeaderParam(name, value); - Adds a header parameter.

message.removeHeaderParam(name); - Removes a header parameter. This should be passed in lowercase.

message.setHeaderParams(object); - Sets multiple header parameters at once.

Query String

message.hasQueryParam(name);

message.getQueryParam(name);

message.getQueryParams();

message.addQueryParam(name, value);

message.removeQueryParam(name);

URL

message.getUrl();

message.setUrl(url);

Content Type

message.setContentType(type);

message.getContentType();

Body

message.setBody(string|object);

message.getBody();

Filtering

message.filter();

message.unfilter();

message.isFiltered();

Additional Functions

All webhooks.io specific functions are prefixed with wh.

wh.http(options)

Makes an outgoing http request which can be used to aggregate, route, or filter webhook messages.

Options:

  • uri || url - fully qualified uri or parsed url object from url.parse()
  • method - http method (default: "GET")
  • qs - object containing querystring values to be appended to the uri
  • headers - http headers (default: {})
  • body - entity body for PATCH, POST and PUT requests. Must be a Buffer or String.
  • auth - A hash containing values user || username, password || pass
  • encoding - encoding to stringify the result body, set this to null to get a Buffer
  • parse_json - if the result is json, it will return as a parsed json object (default: true)

Returns:

{
    statusCode: 200, 
    headers: {}, 
    body: {} //or string of content body if parse_json is false.
}

Example: 

// get the results of the webhooks.io plans
var api_result = wh.http({
    url : 'https://api.webhooks.io/v1/plans'
});
wh.email(options)

Sends an email from your recipe.

Options:

  • to - String or array of email addresses to send the message to.
  • from - The text that should be displayed as who the message is from.
  • subject - The subject that should be used for sending the message.
  • important - If the message should be marked as important or not (default: false)
  • body - The actual text for the message.
  • reply_to - All messages are sent from alerts@webhooks.io, so this is an address for which the email can be replied to.

Returns:

void - This function does not return anything.

Example: 

// lets assume the payload of the webhook was in the following very simple format.
{"charge_id" : 1000}

// Call the function to the email.
wh.email({
    to: ["username@yourdomain.com"],
    from : "Charge Alert Bot",
    subject: "New Charge!",
    body: "A new charge was created the id is " + message.getBody().charge_id
});
wh.lambda(options)

Modifies the destination parameters so the message will be routed to invoke a AWS Lambda function as a result of the webhook request. This function will essentially resolve to the information at th

Options:

  • accessKeyId - Your AWS access key id
  • secretAccessKey - Your AWS secret access key
  • functionName - The Lambda function name. Length constraints: Minimum length of 1. Maximum length of 64.
  • invokeArgs - JSON that you want to provide to your Lambda function as input.

Returns:

Modified message object. The message object will automatically be updated in the request, so nothing needs to be done with the output.

Example:

var message = wh.lambda({
    accessKeyId : "your-aws-access-key-id",
    secretAccessKey : "your-aws-secret-access-key",
     functionName : "your-function-name",
     invokeArgs : {"hello": "world"}
 });
wh.log(data, type)

When writing webhooks.io recipes it can be helpful to log data to the console. To allow for this, you can call this function.

Options :

  • data The data/message to be logged.
  • type The type of log record to add. Valid options include log, info, and warning (Default: log)

Returns: Void

Examples: 

// simple log entry echoing Hello World
    wh.log('Hello World');

// making an http request and then logging return.
  var api_result = wh.http({
      url : 'https://api.webhooks.io/v1/plans'
  });

  wh.log(api_result);

Supported Libraries

In addition to the custom library, we also support some commonly used javascript libraries that can be used in your recipe scripts.

Library Version Details
Moment 2.9.0 Parse, validate, manipulate, and display dates in JavaScript.
lodash 3.3.1 Details...
Chai 2.1.0 BDD / TDD assertion library
xml2js 2.0 Details...
JSON2 2.0 Details...
AES 2.0 Details...
SHA1 2.0 Details...
SHA256 2.0 Details...
HmacSHA1 2.0 Details...
HmacSHA256 2.0 Details...
MD5 2.0 Details...

Example Usage

Moment

Any moment function can be accessed by prefixing the function with moment() as shown below.

// Return a unix timestamp.
moment().unix();

Full Moment documention

Lodash

Any standard lodash function can be accessed in your recipes by prefixing the function with _.

// get the difference between two arrays.
_.difference([1, 2, 3], [4, 2]);
// → [1, 3]

Full lodash documention

Chai

Any standard Chai function can be accessed in your recipes by prefixing the function with assert, .

// ensure a value in the message body is equal to a specific value.
assert.equal(message.getBody().shipper, 'ups', 'Shipper is UPS');

Full lodash documention

Xml2JS
JSON2
AES
SHA1
SHA256
HmacSHA1
HmacSHA256
MD5
Getting Started Examples