Webhooks

Webhooks are one of the ways that programmers can easily hook into our API to leverage the power of other websites.

Quite simply, a webhook is a URL that you can request when an important event happens. We handle both incoming and outgoing webhooks. So if you want to hook into us, awesome. If you want us to notify you and call your webhook, we can do that.

Authentication

When each webhook is created, you'll receive a unique token that you may use to authenticate and identify your call. Do NOT share your "bearer" token with anyone - as anyone who presents (or "bears") your token may call your pipe.

You may present your bearer token by...

(1) - Add an "Authorization" HTTP header, using the Bearer scheme. Simply add "Authorization: Bearer 12345", to the headers of your HTTP request. Replace 12345 with your actual bearer token.

OR (2) - Add the bearer token to the key value pairs in the JSON encoded data using the key "bearer". For example,

{
  "bearer" : "12345",
  "foo" : "bar", 
  "faz" : "baz",
  ... 
}

OR (3) - Add the bearer token to the url as follows

https://www.pipethru.com/site/servers/webhooks?bearer=12345
...and replace 12345 with your acutal bearer token.

Data Format - You call us

When you call our webhook, please POST to the URL https://www.pipethru.com/site/servers/webhooks

We only accept JSON encoded dictionary or key / value pairs. For example...

{
  "foo" : "bar",
  "first_name" : "John",
  "last_name" : "Baz",
  "date_sent" : "2012-02-10 14:22:33"
}

Any datetime values should be formatted as "YYYY-MM-DD HH:ii:ss".

When you are creating the action part of the pipe (the part in the "We will..."), you may use any of the keys from the data you sent. Simply enclose them in double curly braces when you use them in the available fields. So, in the example above, you may use {{foo}}, {{first_name}}, {{last_name}}, and {{date_sent}} and we will replace them with the values that you sent.

A special note for invoices

In the JSON encoded data that is passed along to our webhook, you can pass in invoice line items. These line items are necessary for creating invoices with PipeThru. To the JSON object add a "lines" field - this is an array of objects. Each line object can contain a "name", "price", "description", and "quantity". Example below...

{......
 lines : [{name : "Foo Widget", price : 12.34, description : "Optional description", quantity : 1}, 
          {name : "Widget Name 2", price : 55.44}, 
          {name : "Third thing", price : 19.95}, ... ],
......} 

Data format - We POST to your URL

If we are calling your webhook, then we will POST a JSON encoded dictionary of the key / value pairs available from the source app to the URL you provide. We will also include the bearer token associated with this webhook so that you know the call is from us. For example, in the source app of Twitter - when someone tweets, we will provide you the following data.

{
  "bearer" : "12345",
  "handle" : "thisandyjones",
  "tweet" : "We handle webhoooks!",
  "date" : "2013-06-23 19:11:22"
}

Please see this handy tool to see the data that each source app provides.

We strongly recommend that you only use https when using webhooks to safe-guard the bearer token. We will POST the above data to your URL.

Any HTTP 200 response, with or without any reply, is considered a successful delivery to you. Upon failure, we will try up to 4 more times to send the data to you. We will exponentially back-off on each failure. If the first attempt fails, we will wait 4 minutes until our next try, then 16, then 64, etc. If we cannot reach your webhook by the 5th attempt, we will stop trying.

Return data

Upon any request to us, success or failure, we will respond with a 200 response code and the following JSON encoded data...

Success

{
  success : true,
  message : "Okay"
}

Failure

{
  success : false,
  message : "Informative error message, suitable for display to a human"
}

Webhooks can fail for any number of reasons. The primary two are that the pipe your created in PipeThru was not configured correctly, and that the receiver of the data was either down or not responding at the moment. You are responsible for retrying at a later time. Any response outside of this should also be considered a failure.

2ms - 2018-12-10 11:08:34