Recipes: Getting Started



Recipes allow you to transform a webhook payload in any way imaginable. Can be written quickly via standard javascript code. To aid in the creation of your recipes an API is also provided along with some well known javascript libraries.

To better understand how recipes can be implemented the following use cases will be explored in more detail:

In each of these use cases, we will use an eCommerce application as the example application that is providing the webhook.

The actual payload data can be returned by calling message.getBody(), so assume this is the current payload.

{
    "order" : {
        "id" : 1000,    
        "amount" : 100, 
        "shipping_method" : "ups",
    "order_items" : [
        ...
        ]
    },
    "customer" : {
        ...
    }
}

Filtering

In many cases webhook providers offer an all or nothing subscription when really you only want a sub-set of the webhook requests. Filtering in the webhooks.io system allows you to drop requests that do not meet your specific criteria. You could absolutly do this at your endpoint, however if you are looking to reduce the workload on your system you can easily do it via the relay.

Event Type Filters

Using our eCommerce application example, you might only be interested in receiving the product.create event and not product.update event. However the eCommerce app does not allow you to just specify that you only want the webhooks for product.create. In this case a filter to only allow product.create events to be relayed.

// if the value in event is not from product creation, then just filter.
if(message.getEvent() !== 'product.create'){
    // the result object has a function called filter, which will drop the webhook request.
       message.filter();
}

Content Based Filters

Perhaps you are only concerned about orders that are over $100. Similar to the event filter, you could write a simple script that would filter out all requests that are under $100.

// if the value of order.amount in the payload is not over $100, we will drop.
if(message.getBody().order.amount < 100){
    // the result object has a function called filter, which will drop the webhook request.
       message.filter();
}

Transforming

Conforming to a providers payload format might not always be optimal. Luckly, transforming the payload to something suitable is a snap. In the example below shows how to transform the order payload to something simple and change the content type so the destination will receive form data instead of raw json since that is what our endpoint requires.

/*
    Simplify the payload so it only includes the id of the order, the order amount, 
    and the total number of items in the order.
*/

var new_payload = {
    order_id : message.getBody().order.id,
    amount : message.getBody().order.amount,
    item_count : message.getBody().order.order_items.length
};

// now set the new message body.
message.setBody(new_payload);

// Next, we need to ensure we sent this as a form data instead of application/json
message.setContentType('application/x-www-form-urlencoded')

At this point the message content has been modified and will be relayed as form data instead of a json payload.

Content Routing

In some cases it might be helpful to route the webhook request to a different endpoint based on the content. 

// depending on how the order is to be shipped, modify the endpoint to update the proper system.
if(message.getBody().order.shipping_method === 'ups'){
    // modify destination url to send to UPS endpoint
       message.setURL('https://api.ups.com/some-endpoint');
}else if(message.getBody().order.shipping_method === 'fedex'){
       // modify to send to FedEx
    message.setURL('https://api.fedex.com/some-endpoint');
}

It is also possible to use transforming and content routing to wire up some complex logic. For example, if you need to modify the payload to make a valid API call to a shipping provider.

Aggregating via HTTP

var shipper_details = wh.http('https://api.my-ecommerce-store.com/shipper_info/' + message.getBody().order.shipping_method);

// Now use the result of shipper_details to update your payload or do more advanced routing.

Piping to AWS Lambda

var lambda_props = {
    accessKeyId : '{aws-access-key}',
    secretAccessKey : '{aws-secret-access-key}',
    functionName : 'proces_order',
    invokeArgs : message.getBody()
};

wh.lambda(lambda_props)
API and Libraries