Scheduled callbacks for your web applications

1. Schedule a Revalee callback in your server-side code.
2. Time elapses to the specified time.
3. Your web app receives a callback with parameters.

Revalee can simplify your web application's workflow when events are required AFTER the normal handling of a web request. You can write all of your scheduled activities in the same toolset and application as the rest of your server-side code.

Common Uses

There are many functions your web application could perform if it had someone always waiting to click on a link at the perfect time. Revalee can allow your website to double as your backend processor. Not all tasks are appropriate for a web application. Long running processes are a bad match. However, most out-of-band tasks are relatively quick and use the same database technology as the web application. A scheduled callback makes it easy to write up another page/handler/action to perform a task that would otherwise require an entirely separate application to launch on a dynamic schedule.

Here are some common ways to utilize the power of scheduled callbacks:

  • Sending reminder email messages.
  • Running recurring automated reports.
  • Scheduling daily maintenance functions.
  • Expiring accounts or subscriptions.
  • Canceling incomplete transactions.
  • Consolidating multiple notification messages.
  • Purging temporary files.

Here is a simple scenario

Let‘s say your website offers a 30-day free trial subscription and 3 days before expiring you want to send an email message to promote the benefits of staying on as a continuing customer. You‘re going to need to create a batch process to query for all of the soon-to-expire users. Next you‘re going to need to wrap that query up in a process that can connect to the database, render the custom body text, and send the email message. Plus, you‘re going to need to setup some scheduling system to launch the batch process (presumably nightly). You‘ll also need to be mindful of the performance impact of handling all expiration messages in a single nightly batch.

Alternatively, you can use a web callback. When the user initially signs up for the free trial, register a callback like this:

private void ScheduleExpirationMessage(int userId)
{
   DateTimeOffset callbackTime = DateTimeOffset.Now.AddDays(27);
   // The callback should be in 27 days from now
   Uri callbackUrl = new Uri(string.Format("http://mywebapp.com/ScheduledCallback/SendExpirationMessage/{0}", userId));
   // Register the callback request with the Revalee service
   RevaleeRegistrar.ScheduleCallback(callbackTime, callbackUrl);
}
Revalee Workflow

In 27 days, your web application gets a request for ScheduledCallback/SendExpirationMessage. You can use the userId parameter to lookup the user‘s information and build an email message using the same techniques used to send a welcome message. It will all be handled by the code in your web project. Here is an example in ASP.NET MVC, although any web request handler could be used:

[AllowAnonymous]
[CallbackAction]
public ActionResult SendExpirationMessage(int id)
{
   // TODO Lookup the user's information using the 'id' parameter and send the trial expiration message
   // ...
   return new EmptyResult();
}

There are no extra scheduled tasks to create. No batch level processing. No separate application to deploy. You can test your code with the same automated testing methodology, because you only have code in your web application. It provides a very clean architecture to perform all kinds of out-of-band tasks.

Reliability

The Revalee Service commits callback requests to disk before returning a unique tracking identifier. If the service is ever halted or terminated abruptly, then all callback requests will be reloaded and dispatched as soon as they are due. Retry heuristics ensure that all scheduled callbacks are resilient against temporary outages. Numerous performance counters are available for monitoring activity of the service.

Performance

The Revalee Service was built for high-performance scenarios. It can handle the registration and dispatch of 100‘s of callbacks per second on a single instance. Memory load and CPU utilization are also minimal even under heavy load. The latency between requesting and receiving an immediate callback averages around 20ms when processed locally.

try it out get involved

Server Setup

The first step is to install the service on a server that your web application has network access to. Simply expand the contents of the Revalee.Service-2.3.0.zip file into a folder (for example: C:\Program Files\Revalee\). Next, open a command prompt with elevated privileges and type the following command.

To install the service:

Revalee.Service.exe -install

To remove the service:

Revalee.Service.exe -uninstall

Once the Revalee Service is installed, it can be started or stopped like any Windows Service. The default settings for the service are stored in the Revalee.Service.exe.config file, located in the same folder as Revalee.Service.exe. The default port number that the service will listen on is 46200 using the http protocol. [http://+:46200/]


It is important to secure the Revalee Service against unauthorized usage. The risks of an unsecured Revalee Service is similar to an open SMTP relay.

By default, the service only allows callbacks to be requested from the local host server and executed against URLs starting with "http://localhost" or "https://localhost". You can add and remove authorizations by editing the Revalee.Service.exe.config file located in the same folder as Revalee.Service.exe. Make sure to restart the Revalee Service to load any changes made to the Revalee.Service.exe.config file.

For example, the following section of the configuration file has an authorization added to support the Revalee Sample Site. It allows callbacks to any URL that starts with "http://localhost:64646/RevaleeTest/Callback" to be requested from web servers on any network and for the callback to be retried 3 times before abandoning it.

<securitySettings>
   <urlAuthorizations>
      <authorize
         urlPrefix="http://localhost"
         fromAddresses="127.0.0.1,::1"
         retries="2" />
      <authorize
         urlPrefix="https://localhost"
         fromAddresses="127.0.0.1,::1"
         retries="2" />
      <authorize
         urlPrefix="http://localhost:64646/RevaleeTest/Callback"
         fromAddresses="0.0.0.0/0,::/0"
         retries="3" />
   </urlAuthorizations>
</securitySettings>
				

The urlPrefix parameter is an absolute URL that starts with either "http:" or "https:". Callbacks will be accepted only the requested callback URL matches exactly or starts with this value.

The fromAddresses parameter is a comma-separated list of permitted IP addresses and CIDR blocks. Both IPv4 and IPv6 are supported.

The retries parameter is integer count of the maximum number of retries that will be performed when an HTTP error occcurs when executing the callback.

Client API

REST Interface

Execute an HTTP PUT against {scheme}://{host}:{port}/Schedule?CallbackTime={time_string}&CallbackUrl={full_url_to_callback}

{scheme} = the protocol, either http or https, to use when connecting to the Revalee.Service.exe (default: http)

{host} = the hostname or address of the server running the Revalee.Service.exe

{port} = the port number that is configured within Revalee.Service.exe.config (default: 46200)

{time_string} = the time you want the callback to occur in the ISO 8601 date/time format

{full_url_to_callback} = the absolute URL that will be requested on the callback (URL encoded)

The callback will come via HTTP or HTTPS POST. The response stream will contain a confirmation number in the form of a GUID.

For example, sending...

PUT http://127.0.0.1:46200/Schedule?CallbackTime=2014-12-24T23:00:00Z&CallbackUrl=http://mysite.com/WakeUp.aspx

... will yield a callback to:

POST http://mysite.com/WakeUp.aspx

ASP.NET Client Library

A .NET assembly is available for making callback requests from any ASP.NET application (WebForms or MVC).

One-time Callbacks

Here is a simple example in C# of setting up a one-time callback in 1 hour:

// The host address of the server that is running the Revalee service.
var serviceHost = "localhost";
// The time you want the callback to occur.
var callbackDelay = TimeSpan.FromHours(1.0);
// The absolute URL that will be requested on the callback.
var callbackUri = new Uri("http://localhost/Home/Callback?id=123456");
// Send the callback request to the server.
Guid callbackId = RevaleeRegistrar.ScheduleCallback(serviceHost, callbackDelay, callbackUri);

The assembly includes other member functions to work with callbacks in the Revalee.Client namespace.

  • RevaleeRegistrar.CancelCallback() - Cancels a previously scheduled callback request.

  • RevaleeRegistrar.CancelCallbackAsync() - Asynchronously cancels a previously scheduled callback request.

  • RevaleeRegistrar.ScheduleCallback() - Schedules a callback at a specified time.

  • RevaleeRegistrar.ScheduleCallbackAsync() - Asynchronously schedules a callback at a specified time.

  • RevaleeRegistrar.ValidateCallback() - Verifies that the ASP.NET request was originally requested from this web application.

Recurring Callbacks

Here is an example of setting up 3 recurring callbacks in web.config. (At the top of every hour plus every day at 3:30 AM and 8:15 PM):

<configSections>
   <section name="revalee" type="Revalee.Client.Configuration.RevaleeSection" requirePermission="false" />
</configSections>
...
<revalee>
   <clientSettings serviceBaseUri="http://localhost:46200" authorizationKey="_add_your_secret_key_here_" />
   <recurringTasks callbackBaseUri="http://your.website.com/">
      <task periodicity="daily" hour="03" minute="30" url="/Recurring/Daily.aspx" />
      <task periodicity="daily" hour="20" minute="15" url="/Recurring/Daily.aspx" />
      <task periodicity="hourly" minute="00" url="/Recurring/Hourly.aspx" />
   </recurringTasks>
</revalee>
...
<system.webServer>
   <modules>
      <add name="RevaleeRecurringTasks" 
         type="Revalee.Client.RecurringTasks.RecurringTaskModule, Revalee.Client" 
         preCondition="managedHandler" />
   </modules>
</system.webServer>

The assembly includes other member functions to work with recurring callbacks in the Revalee.Client.RecurringTasks namespace.

  • RecurringTaskModule.GetManifest() - Gets the current ITaskManifest that manages recurring tasks.

  • RecurringTaskModule.RecurringCallbackDetails - Provides information the original callback request.

  • ITaskManifest.AddHourlyTask() - Creates a recurring hourly task.

  • ITaskManifest.AddDailyTask() - Creates a recurring daily task.

  • ITaskManifest.RemoveTask() - Cancels an existing recurring task.

API Reference

The complete API Reference for the Revalee.Client and Revalee.Client.Mvc client libraries is available.

Download

Windows Service

A Windows Service used to store and initiate callbacks to your web application.

Download Now

System Requirements: Windows XP or later

The Revalee service is also available on Chocolatey. To install on a Windows computer, use:

cinst Revalee.Service

ASP.NET Client Library

(Optional) Easily embed callback requests in your .NET web application code.

Download Now

Dependencies: .NET Framework 4.0+ (only System, System.Core, System.Web assemblies are referenced)

The Revalee client library is also available on NuGet. To include in a .NET 4.0+ project, use:

Install-Package Revalee.Client

Alternatively for ASP.NET MVC projects targeting .NET 4.5+, a specialized Revalee client library is also available on NuGet. To include, use:

Install-Package Revalee.Client.Mvc