In this article, we’ll provide technical information about Funnel’s webhook. Please see this article for a higher-level overview.
Overview
This is a webhook REST API for sending links containing files to Funnel via a POST request. Below, we will explain everything you need to set it up, including how to authenticate, build your request, explain the different error codes, and troubleshoot.
Note that this solution is not for connecting a database or other storage solution to Funnel. It's a solution for sending links with files to Funnel. Much like our file import via email, only more secure and reliable, as well as able to send larger files.
Access and Authentication
In order to authenticate, you need a secret token, generated through Funnel. It must be sent in the x-funnel-fileimport-token header of the request or it will be denied access.
API Limitations
Throttling
If you send an abnormal number of requests or at a very high frequency, your requests may be denied.
Supported file types
CSV
TSV
XLSX
ZIP (containing one or more of the file types above)
File size
To ensure a smooth experience, please ensure that files are 1 GB or less.
Endpoint and authentication
Use the endpoint URL to send file links to Funnel via a POST request. To authenticate, you must include the token generated in Funnel in the x-funnel-fileimport-token header sent with your request.
Links
The request you send to Funnel must include a link to a file, not the content of the file. The links to your files need to be HTTPS, and publicly accessible, or the URLs need to be pre-signed. They must be sent as a single string (one link) or a list in a JSON body like this, for example:
Single link:
"https://link-to-file.csv"
or a list of links:
["https://link-to-file-1.csv",
"https://link-to-file-2.csv"]
Deprecated alternative (will be removed in upcoming updates)
Single link:
{"urls": "https://link-to-file.csv"}or a list of links:
{"urls": ["https://link-to-file-1.csv",
"https://link-to-file-2.csv"]}
Setup
To set up a webhook integration with Funnel, you will need to:
Generate a webhook URL and secret token in a Funnel File Import Data Source
Start by heading to the Data Sources section, click "Connect Data Source", and select File Import, or Webhook from the list
Give the File Import source a name and make sure Webhook is selected under transport types
If you already have a File Import source, you can click on “Transport types” in the top right corner of the existing source, select the webhook transport type and click save.
Optional: Under the Files section in Funnel, you can upload a sample file and configure the Data Source before setting up the automation. If you don't, you'll need to configure the source after at least one file has been received.
Set up a service or lambda to send an HTTP request to the webhook URL containing links to the files you want to import into Funnel. Some common examples are Google Cloud Functions, Azure Functions, or AWS Lambda. You may also use low-code tools such as Zapier or Microsoft Power Automate
Have publicly available links containing files to be imported into Funnel. They cannot be password protected. This could be publicly signed URLs to files on for example AWS S3, Google Cloud Storage or Azure Blob Storage
Simply put:
Generate a webhook URL and token in Funnel
Have publicly available files with data stored somewhere
Set up a service on your end that sends HTTP requests to Funnel with links to the files to be imported into Funnel
Examples
Use case guides
Implementation examples
Below are some examples of how to implement the webhook integration with Funnel in different languages.
cURL
curl -X POST -d '["https://cloud-storage.com/file-number-one.csv", "https://cloud-storage.com/file-number-two.csv", "https://cloud-storage.com/file-number-three.csv"]' -H "Content-Type: application/json" -H "x-funnel-fileimport-token: 12345-12345-12345-12345-12345" https://fileimport-webhook.funnel.io/123-123-123-123-123
Python
import requests
webhook_url = "https://fileimport-webhook.funnel.io/123-123-123-123-123"
headers = {
"Content-Type": "application/json",
"x-funnel-fileimport-token": "12345-12345-12345-12345-12345"
}
data = [
"https://cloud-storage.com/file-number-one.csv",
"https://cloud-storage.com/file-number-two.csv"
]
response = requests.post(webhook_url, headers=headers, json=data)
// Response: 200 OK
Node.js
const https = require("https")
const data = JSON.stringify([
"https://cloud-storage.com/file-number-one.csv",
"https://cloud-storage.com/file-number-two.csv"
])
const options = {
hostname: "https://fileimport-webhook.funnel.io",
port: 443,
path: "/123-123-123-123-123",
method: "POST",
headers: {
"Content-Type": "application/json",
"x-funnel-fileimport-token": "12345-12345-12345-12345-12345"
},
}
const req = https.request(options)
req.write(data)
req.end()
// Response: 200 OK
Error Codes
200
OK. The request was successful and Funnel will try to import files from the links provided. If everything goes well, the files should show up in your data source shortly.
400
Bad request. Make sure you have added the urls in your data request and it includes valid links. It should be included in the body of the POST request. Please see the examples above for the correct format.
401
Invalid credentials. Make sure you submit the correct secret token for the webhook URL. It should be sent in the x-funnel-fileimport-token header of the request.
500
Internal server error. Something is wrong on our end.