WebHook PUT

Introduction

The WebHooks API is designed to help you inject a web hook into your user’s form. We believe this API will help reduce the friction your users experience integrating with your site. Let’s compare the steps your user would have to go through to set up a traditional site-to-site web hook integration to a Web Hook set up through the API.

Traditional Web Hook - Before the introduction of this new API, your users had to follow these steps to set up an Web Hook Integration

• Get API key from Wufoo site
• Go to your site to receive a URL and Handshake Key
• Create a new Web Hook integration
• Paste the URL and Handshake Key into the newly created integration & save

Using the Web Hooks API - With the introduction of this API, the steps are greatly reduced

• Get API from Wufoo Site
• Choose form(s) to which you want to hook

Reducing the number of steps your user takes to connect your site to ours increases conversion rate and decreases user frustration. This is a win-win-win. To further reduce friction, you could use the Login API to skip the API retrieval step. If you are unsure how to get started with our APIs, please read our intro page for information on authenticating, sending and processing your request.

Request Format

This API accepts PUT requests in the following format:

https://{subdomain}.wufoo.com/api/v3/forms/{formIdentifier}/webhooks.{xml|json}

and DELETE requests in the following format:

https://{subdomain}.wufoo.com/api/v3/forms/{formIdentifier}/webhooks/{webHookHash}.{xml|json}

{subdomain}

This placeholder must be replaced with your subdomain.

{formIdentifier}

This placeholder must be replaced with your URL or hash.

{xml|json}

You must choose between xml or json for your return format

The PUT parameters

The following parameters must be passed as post parameters to the Web Hook API

url - this required parameter represents the URL on your server that the Web Hook will call when a new entry is submitted. We do validate the URL and reject malformed URLs.

handshakeKey - this optional parameter is described in the Web Hook integration getting started documentation.

metadata=true - this optional value parameter the Web Hook to send along form/field metadata

A Note About PUT Request

PUT call is idempotent (see this stack overflow posting for more info), which means that you may safely make this call multiple times with the same data. This prevents you from accidentally adding 10 of the same Web Hooks URLs to one form. What this means to you is that this call can be used to both create and update a Web Hook.

Let’s see what this means in a use-case. You make one PUT call to the Web Hook API with the url, meta and handshakeKey parameters, but then your user decides to provide a different handhsakeKey. If you make a second API call with the same url with a new handshakeKey, the system will update the web hook with that unique url to the value provided in the handshakeKey parameter. So, in this case, think of the url parameter as a unique key for editing.

Sample PUT Response

Below is a sample response from a fictional PUT call to the Web Hook API.

<WebHookPutResult>
    <Hash>{webHookHash}</Hash>
</WebHookPutResult>

The <Hash> element

This is an unchanging value representing the widget. Remember to save this value, because it acts as the key to your web hook and you can’t query for it again. If you don’t store this value, your user will have to delete the Web Hook from the Wufoo UI. If you do store it, calls to the DELETE method will properly function.