Webhooks

 

The Integration Purpose

As described at Wikipedia - Webhooks:

Web hooks are user-defined callbacks over HTTP. They are intended to allow web applications to become more extensible, customizable, and ultimately more useful. Many web applications only have a request-based output mechanism: web APIs. They lack an event-based output mechanism, and this is the role of web hooks.

Product Description

Since Web Hooks are not a ‘Product’, we’ll try to give you an example instead. If you create an application on your own web site that requires data from Wufoo, you can create a script on your server that is called by Wufoo whenever a form is submitted. To that script we will pass the FieldID (see the API for a more detailed explanation of FieldIDs) and value for your submission as post parameters.

Here is our own screencast describing WebHooks and how Wufoo uses them:

What You Need To Get Started

URL - This is a URL on your server. HTTPS is not required, but it is recommended.

Handshake Key - This is a an optional key that you choose as an authentication mechanism to prevent spam to your Web Hook. This key will be included as a post parameter when our servers call yours. If you use this key, you should compare it to your copy to validate that the submission is legit.

Errors

Errors happen, when they do, they’ll appear in the Error Log. If you see an error in your Error Log that you don’t understand, please contact support and we’ll investigate the problem.

Why do I need this?

So you’re dubious about learning yet another technology concept. You are not alone. But, if you give this just a few moments of your attention you’ll notice that it solves the thorniest parts of an integration: the balance between timely data delivery and service over-use.

Let’s put this into perspective with a Wufoo example. You’re managing 50 forms for a client and they need this data processed quickly - let’s say every 5 minutes. Now let’s remember that your Wufoo API access is restricted to 5000 requests per day. You soon learn that you’ve chewed through the limitation quickly.

Another issue is the ‘long polling script’ issue that an integration poses. Whether you use cron or a long polling script, you’re still dealing with your scripting language from the command line where it is difficult to debug. Or, if your cron just fires a cURL call to a web page in your domain that does the work you’re still subject to the time limitations that a long-running script poses. For example, what if your server crashes during script execution?

Finally, there’s the concept of data synchronization. In the typical API scenario you must keep track of the last entry ID received so that you can augment your API request to get only the most recent entries since your last call. Web Hooks allow you to do away with this headache. With a web hook, you know that the submission you’re receiving is the most up-to-date.

How do I develop against this?

Developing against your Web Hook is simple. To begin, you’d simply look at your data. To view a Web Hook in action, simply sign up for a RequestBin url and use that as your Web Hook URL. You’ll see then how the data is transmitted. We’re sending you a POST with the API ID from the API Information and the user-submitted data.

Once you’ve got a handle on what your data looks like, you can point your Web Hook URL to an endpoint on your web server that parses this data and does something cool with it, like update your CRM. 

What does the post look like?

To see a post in action, check out the demo form we’ve set up here, which sends a post back to this RequestBin address. The API info for this form is shown below.

Web Hook Fishbow Form API Info

Metadata

If requested, wufoo will send along metadata about the fields and forms for your webhook. To set it up for your webhook, simply check the ‘Include Field and Form Structures with Entry Data’ box, as shown below.

Web Hook Metadata

With the metadata option turned on, you’ll receive two new post parameters with your post: FieldStructure and FormStructure. These parameters will mirror calls to the field and form APIs respectively, as called with the ‘.json’ format. This means that the two post parameters will be filled with json data.

Can I get the URL for my File Upload field?

Yep. File Upload behave differently than standard fields. We add an extra field with the Field ID appended by -url. So, for the example shown below, the Attach a File field would be represented by two post fields, the second of which contains the full URL.

Field109 => bearseatbeets.jpeg.jpg
Field109-url => https://fishbowl.wufoo.com/cabinet/w7x1p5/Q6gDdhb9tac%3D/bearseatbeets.jpeg.jpg

What’s the correct date format?

We’ve had some questions about why DateCreated would be in the format 1976-08-13 08:45:34 while a user-supplied date is in the format 19760813. Here’s why: we send user-supplied data to you in exactly the same format required when you post data to us through the Entries POST API.