Webhooks

Press Play on the video player above to view this training video. The video script is presented below if you prefer to read.

First of all, what is a Webhook? You can think of a Webhook as a web request that your Files.com site makes automatically, triggered by an event that you determine to some other service, which of course you also determine, for the purpose of kicking off a process. The process could be anything from very simple to very complex.

Okay, let's see what a Webhook actually looks like.

We'll start with a very simple example. You can see that I've got two windows here open. [see video]

I'm going to show you how to create a simple Webhook on your Files.com site. And then I'll show you what it looks like when the Webhook is triggered. After that we'll take a look at a few more options to get more advanced.

For starters, a Webhook on Files.com is a folder behavior. So, in order to add one, we go into Folder Settings for any folder and scroll all the way to the bottom where we choose webhooks. And, as is the case for most folder settings, this is going to be form driven and fairly self-explanatory. What you need is going to be displayed in front of you.

The first thing we want to add is the web address of the webhook handler or receiver, the primary URL. And on this window [see video], you can see I'm on my Files.com site. When I switch to this other window, I'm in a service called Pipe Dream, which was formerly known as Request Bin. This is a service that you can use for free online to check your development projects. Pipe Dream works for web requests of all sorts, but it's really best for testing Webhooks specifically. So, this is our endpoint address provided by Pipe Dream. When you log into or start a new pipe dream account, the service automatically creates this for you, so you are immediately ready to test an event.

Click this link to copy the URL [see video]. Now let's go back to our Files.com site. We're going to paste that link here [in the folder behavior interface]. We'll talk in more detail about what the rest of these settings are later. But the other thing you want to decide right off the bat is: what do you want to trigger this Webhook? So, when something happens in this folder, this Webhook is going to fire, and a request is going to be sent to this address. Do we want to trigger it on all file operations? Or do we want to choose which of these it gets triggered by? [see selection in web interface]

We're just going to look at a simple example now. We might as well say trigger on all file operations. And we'll also expand this and look at more advanced settings in just a moment. But for now, this is all it takes to add a Webhook. It's very simple. Click Save. We now have a Webhook added to this folder.

You may have noticed there's already been a GET request over here [in the Pipe Dream interface], and that is because when you create a Webhook, Files.com automatically sends a test request to see if it gets the information back that it needs.

It does need to see a 200 response from your process's endpoint, or it considers that a failure and will continue to try to make that request over increasing intervals over a period of three days. So, you want to make sure that your process endpoint [your webhook receiver] is active, and that it is able to accept the request and also able to respond with a success response [a 200 status code].

Let's grab a file and upload it to this folder. [see video] This is the basic folder operation. We just uploaded a file and we see this is a text file. If we come back over here [Pipe Dream interface], we see a GET request. This is the simplest form of a webhook. This tells us everything that happened. It was a GET, so any parameters were sent in a simple URL. And it also gives us additional information here. [see video] The values that were passed with the URL include what happened, we created a file, it tells us when this happened, and it gives us the full path.

That information is mirrored right there. It also lets us know that this upload was created via the web browser. Had I been using an SFTP client, an FTP client or WebDAV, this would tell me which one of those I used. This gives me a reiteration of the path, the size of the file, and what type of item are we talking about. It's a file in this case. It could also have been a folder. And not only that, who did the upload - administrator2196. That is who I am currently logged in as, and so that is why that's the information we're seeing here. Very simple.

Now let's take another look at this webhook to edit it. [see video] We can use the same primary URL. But now we're going to look at some other options. First, let's open the advanced settings.

Let's make this a POST instead of a GET. Depending on the app that you're developing, or the process that you want to trigger, it may be that your system doesn't want to receive a GET request; it wants a POST instead.

The other thing might be that you want to add some custom headers. Let's say we have something called special header. And let's say the value is just like a token for some purpose. We don't really need any other key value pairs in the body, but we just want to send that header. Perhaps it's so we can identify that the post is coming from an authorized requester. For instance, you want to identify that this is coming from your Files.com site so that the endpoint doesn't accept, respond to, or kick off a process that comes from an unauthorized requester. Should we change the encoding on this? [see selection interface] Let's just say, No, it's fine as it is.

Now let's talk about the backup URL. While we're looking at this, this is your main address. This is the one address that we have right now where requests can be sent whenever a Webhook is fired. But let's say that your process is very complex, has multiple front-end servers, and if one server happens to be down for maintenance, or not responding quickly enough, your process is designed to allow another one of your front-end servers to respond to the request.

You can add additional URLs here. [see web interface] You can add as many of these as you need. We're just going to use the one right now, because we only have one endpoint provided by pipe dream.

We'll turn this into a POST. Click save. Now we see that we did get a POST request from the automatic test. [Pipe Dream interface] And let's take a look and see what else is coming through here. We see that it's from the same host. But here we have special header and that token that I added. You could use this for a whole variety of purposes and could also add multiple headers should your process call for that.

Let's go ahead and create a POST.

We’ve uploaded a couple files. Now we've got two files there. [see video]

This one recorded as this POST indicating another CREATE, so we know it's an upload. Here's the name of the file, and we can see the upload was via the web. All the information that you would want is here.

You can also use this to conditionally trigger different types of processes.

Let's do a delete. We'll delete these two files and see what happens. [see video] We said that our webhook will fire on all events, So we got two new POSTS that just came in. Let's take a look. Action is destroy, so we know that this file was deleted. And all the other information that we're looking for here, you still have the special headers that we set up.

Now we know there are no files left here. Why? Because we have one destroy here and another destroy here. So, we had a couple of creates and a couple of destroys to cancel them out. So that's what the actual Webhook data looks like. Now we've seen a simple example of what a Webhook looks like under the hood, so to speak. You can see that we can send GETS and POSTS.

Let's do one more example, and we'll use this interface. [custom reporting web interface - see video] We put together an interface that's designed to simulate a report generator that is populated by Webhooks.

Let's go back to our folder settings. We can delete this URL and add a new one. It's a script that's going to receive this Webhook process it, and then record it to a log file, which will then start displaying it here when we refresh the browser. [see video]

Now let's say we want to trigger on uploads, downloads, updates, and deletions, but we don't need to trigger on moves or copies. We can uncheck those. That's easy enough to do. Let's see if there's anything in advanced settings. I do prefer POSTs instead of GETs, so we'll select that. And for this sample, we don't need to add any headers or body values. We're just going to use the values that are automatically generated by the Webhooks themselves. Now we're good to go. Let's click save.

Now we've got a new Webhook. Let's see what happens when we upload some files to this folder. Last time we were uploading files one by one. Let's do them in a group this time. Now we have a bunch of files that are all uploaded here. You can see them 6,7,8,9 and 10. And what happens if we refresh? Now we have an updated report. [see video]

We can see the file names, and we can see that 70 bytes uploaded. But let's see what happens if we delete a couple files. Let's delete 6, 7 and 8. Now let's refresh.

Now we see these files were created, these particular ones were deleted. I'll make it total things up for you. So, let's go ahead and upload file 10 again to see an update action. We're going to overwrite the file that's already there.

As you can see, by dividing the Webhooks into their component parts by the actions you choose to trigger them, you can cause different things that occur in this folder to result in different actions being taken at the endpoint. You can start to use your creative thinking to see different actions kick off different processes or different parts of a process.

Okay, let's briefly summarize what we talked about in this session.

Webhooks are one of the absolute best ways to trigger an automation in real time. They're very easy to set up. As you can see from the interface, [see web interface] they're always at the folder level, easy to get to. Just click on folder settings, scroll down through all the settings that you have available here, and go right to Webhooks.

When you have an existing Webhook, you can click Edit, and make any changes that you need.

Note too, that you can have more than one Webhook active in a folder at the same time. Some of the most impressive workflows and automations that we've seen start with Webhooks.

If you have any questions, please feel free to Contact Us or give us a call at 1-800-286-8372.