Walkthrough

This walkthrough provides comprehensive instructions for integrating Funnel Leasing Events and Callbacks (commonly known as "webhooks") into your application. These webhooks deliver event metadata automatically whenever an action occurs within the Funnel Online Leasing product.

This resource focuses on implementation details, offers examples, and guides you through the process of working with webhooks. For a broader understanding of Funnel Leasing Events, please consult the Events Overview section in our documentation.

⚠️

Delivery is handled by a separate service

Funnel's own systems only publish events to an internal queue — the actual outbound HTTP delivery to your callback URL (including retries, timeouts, response-body checks, and retention) is performed by a separate downstream delivery service, not by the Funnel API itself. The specific numbers and requirements in this page (retry counts and delays, the 5-second timeout, the expected response, and the 90-day retention window) describe that delivery service's current behavior as best understood, but they are not something this documentation can verify from Funnel's own systems, and they may change without appearing in Funnel API release notes. If your integration depends on any of these specifics, confirm the current behavior with your Funnel representative rather than relying solely on this page.

Setting Up Funnel Leasing Events

Enabling Funnel Leasing Events (webhooks) involves two main steps:

Setting the callback URL within Funnel Leasing, which we'll cover below.
Responding to events to confirm their reception.

Set a Callback Url

To configure the account callback URL, please contact the Funnel Leasing technical support team at support@funnelleasing.com. Alternatively, you can reach out to your assigned account representative for direct assistance.

Responding to Events

Funnel Leasing dispatches events to a specified callback URL and expects a specific response for verification purposes. A delivery is treated as successful when your callback URL returns any 2xx status code; the response body is not inspected. Any non-2xx status, a connection error, or a timeout triggers a retry mechanism by Funnel Leasing.

⚠️

Failed Callbacks

Too many consecutive failed callbacks will result in Funnel Leasing deactivating webhooks for a callback url. Once deactivated, Funnel Leasing will stop sending events until a new callback url is added. Read more about this behavior in the Failures and Retries section.

Here's a basic example in NodeJS:

Node.js Example

// This sample is stripped down
// Use for reference only
const express = require('express');
const app = express();

app.post('/funnel-events', (req, res) => {
    res.set('content-Type', 'text/plain');
    res.status(200).send('Funnel Event Received');
});

Testing your Callback Url

During the setup process, you can test your callback URL's functionality by triggering a test event through the Funnel Leasing testing API. This ensures that your webhook handler responds correctly to events.

ℹ️

Ask support to confirm

We could not verify a public test-event API from Funnel's own systems while writing this page. If you need to test your callback URL before going live, ask your Funnel representative for the current recommended way to trigger a test event.

Securing your Callback Handler

ℹ️

Confirm current availability

This describes delivery-service behavior we could not verify from Funnel's own systems — confirm with your Funnel representative that this option is still offered before relying on it.

We offer the option to enhance the security of your webhook URL by including an API token in our webhook event requests. If you would like to take advantage of this feature, please contact our support team. Provide them with your API token, and they will configure your webhook requests accordingly.

It's important to inform us immediately if your API token changes. Without notification of the new token, we will continue to send requests using the old token, which will result in failed attempts to communicate with your servers.

While this step is optional, it provides an extra layer of security for your webhook URL, ensuring that only authorized requests are processed. If you have any questions or need assistance with this setup, our support team is ready to help.

Failures and Retries

If your callback url is not reachable or returns a non-successful response, we will retry POSTing the event up to 3 times, with each retry interval being longer than the previous one.

Please note that our requests will timeout after 5 seconds, so callbacks will fail if your server takes longer than that to respond. The retry pattern is described below.

Retry schedule

Up to 3 retries

1First attempt
5 seconds
2Second attempt
10 seconds
3Third attempt
15 seconds

Delays increase with each retry.

The above retry pattern may not always be exact, but it is a good approximation of the retry pattern we use.

Retention Policy

Funnel Leasing retains all events and their associated callback results for 90 days from the time each event is created. Once an event reaches 90 days old, both the event and any related callback results are moved to long-term archive storage and are no longer accessible through the webhooks system.

If your integration requires access to historical event data, we recommend persisting relevant events to your own data store upon receipt. Because events are delivered in real time via your callback handler, that is the appropriate place to capture and store any data you wish to retain long-term.