Engine: Provider Proxy



Provider Proxy enables application providers to easily offload the complexities of sending webhooks with minimal application changes. The only thing that needs to be done is modifying the destination URL at runtime to proxy through the Webhooks.io system. Other than that, the existing process for subscriptions and webhook management can remain exactly the same.

Getting Started

Getting started is quite easy. The first think you will do is create a new application within your account. Once you do that, simply constructing a URL as shown below will get you sending requests through webhooks.io.

You do NOT need to configure versions in your application for this to work. Simply creating the application so you get an application id is all that is required.

  • Endpoint Protocol: This will be the protocol the original endpoint was using. Since all requests need to be sent via HTTPS, if you need to send the request to an insecure endpoint (HTTP), then add the header value of Webhooksio-Protocol: http .
  • Gateway Domain: The domain that webhooks.io uses as their gateway e.g. https://gateway.webhooks.io.
  • Application Id: After you create an application in your account, you will want to grab the application id that is provided and substitute here.
  • Customer Id: This is the ID from your application you want to use to associate the requests with. This is most likely a customer id, but could be any source id you want to associate the requests with. All reporting and analytics will be grouped by this identifier.
  • Bucket Key: Some applications allow their users to have "live" and "test" contexts - like Stripe or Intercom for example. If your application allows for multiple contexts you can use the bucket key to segment requests to each context. This value is completely adhoc and is up to you. If you do not use the concept of different contexts we suggest you use your actual application environment as the bucket key. e.g. production, staging, etc.
  • Domain AND URI: The full domain and URI, minus the protocol, for the original endpoint. This can include basic authentictaion. The webhooks.io system will invoke an outgoing request directly on this value.
  • Query Params: Any query params without the webhooksio- prefix, will pass through to the original endpoint.

Authentication

You must past your API token in the header - similar to all of our other API calls. The header value should be in the form:

Authorization: Bearer {Your-Token}

Valid Header/Query Values

You can actually specify some additional values when sending your request. (we will be expanding these docs shortly.)

  • Webhooksio-Protocol: http, https
  • Webhooksio-Consumer-Name: My Customer Name
  • Webhooksio-Alert-On-Failure: jason@webhooks.io
  • Webhooksio-Recipe-Id: none
  • Webhooksio-Retry-Policy-Id: linear
  • Webhooksio-Retry-Interval: 60
  • Webhooksio-Retry-Count: 10
  • Webhooksio-Headers-Prefix: myservice
  • Webhooksio-Headers: input_id, outgoing_message_id, attempt_id

Sample Curl Request

If your customer had subscribed with the following endpoint:

http://requestb.in/pcjifkpc

To proxy through your webhooks.io account with a very simple retry policy you could simulate that request with the following curl:

curl -X POST -H "Authorization: Bearer {Your-Token}" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Webhooksio-Retry-Policy-Id: linear" \
    -H "Webhooksio-Retry-Interval: 60" \
    -H "Webhooksio-Retry-Count: 10" \
    -d "variable1=one&variable2=two" \
    "http://gateway.webhooks.io/AP81dd181b37e144f28b7f6a8e713623cf/1000/production/requestb.in/pcjifkpc"

In the example above it is assumed that the customer id is "1000" and the bucket you want to group things in is "production".

Proxy Endpoint Functions

The following functions can be used to convert your endpoint to proxy through the webhooks.io system.

JavaScript/Node.js

/**
 * Coverts a URL to a URL that will be passed through.
 * @sync
 * @method convert
 *
 * @param {Object} opts Object that is holding information that will be used to modify the url.
 * @param {String} opts.url The final destination URL
 * @param {String} opts.proxy_hostname The domain that is being proxied to.
 * @param {String} opts.input_id The bucket the request should be proxied through.
 * @param {String} opts.consumer_id The domain that is being proxied to.
 * @param {String} opts.application_id The domain that is being proxied to.
 * @param {String} opts.bucket_key The domain that is being proxied to.
 * @param {Function} callback A function for the callback accepting the following argument 'err, Result'.
 * @example
 *    function(err, Result){}
 */

var convert = function (opts) {
    var local = {};
    // split the url in half using :// as the split location...
    local.url_parts = opts.url.split('://');

    // if the url is to using an input - typically for end user mode...
    if (opts.input_id) {
        local.proxy_part = opts.proxy_hostname + '/' + opts.input_id + '/';
    } else {
    // otherwise the url is for provider platform...
        local.proxy_part = opts.proxy_hostname + '/' + opts.application_id + '/' + opts.consumer_id + '/' + opts.bucket_key + '/';
    }
    // put the URL back together...
    local.final_url = local.url_parts[0] + '://' + local.proxy_part + local.url_parts[1];
    // return
    return local.final_url;
};

PHP

<?php
/**
 * @param string $application_id
 * @param string $customer_id
 * @param string $bucket_key
 * @param string $endpoint_url
 * @param string $gateway
 * @return string
 */
function convert($application_id, $customer_id, $bucket_key, $endpoint_url, $gateway = "gateway.webhooks.io")
{
    // Split the endpoint_url using :// as the split location
    $endpoint = explode("://", $endpoint_url);

    return $endpoint[0] . "://" . $gateway . "/" . $application_id . "/" . $customer_id . "/" . $bucket_key . "/" . $endpoint[1];
}
// Example returns http://gateway.webhooks.io/application_id/customer_id/bucket_key/endpoint_url.com/incoming-webhook
echo (convert("application_id", "customer_id", "bucket_key", "http://endpoint_url.com/incoming-webhook"));

Ruby

Coming soon

.net

Coming soon

Java

Coming soon

Go

Coming soon

Perl

Coming soon

Getting Started