README.md

CalendlyEventWebhook

A simple project for registering and handling Calendly event webhooks.

Installation

1. Add CalendlyEventWebhook reference to your project.
2. Use the IServiceCollection.AddCalendlyEventWebhook method in the ConfigureServices method of your Startup class.
   This will add services required for creating/removing webhook subscriptions and handling Calendly requests.
3. Use the IEndpointRouteBuilder.MapCalendlyWebhook method in the Configure method of your Startup class.
   This will map the route specified in Webhook.CallbackUrl configuration property to a middleware that handles requests from Calendly.
4. Add configuration to your configuration file (e.g. appsettings.json).
5. Implement IEventCancellationHandler, IEventReschedulingHandler, and IEventCreationHandler interfaces whose methods will be called when a matching event is sent from Calendly.

Example:

Host.CreateDefaultBuilder(args)
    .ConfigureWebHost(
        webHost =>
        {
            webHost.Configure(
                app =>
                {
                    app.UseRouting();
                    app.UseEndpoints(endpoints => endpoints.MapCalendlyWebhook());
                });
        })
    .ConfigureServices(
        (context, services) =>
        {
            services.AddRouting();
            services.AddCalendlyEventWebhook(context.Configuration);
        });

internal class EventCancellationHandler : IEventCancellationHandler
{
    private readonly ILogger<EventCancellationHandler> _logger;

    public EventCancellationHandler(ILogger<EventCancellationHandler> logger)
    {
        _logger = logger;
    }

    public Task<bool> Handle(CalendlyResourceIdentifier id)
    {
        _logger.LogInformation("Event {EventId} cancelled", id.Id);
        return Task.FromResult(true);
    }
}

Configuration

The configuration object must be placed in CalendlyEventWebhook section. The following settings are available:

• AccessToken (required) - the Personal Access Token used to authenticate with Calendly
• Scope - User (default) or Organisation - dictates whether the webhook subscriptions should be scoped to a user or the whole organisation
• Webhook object:
  • CallbackUrl (required) - the URL which will be used by Calendly to publish event updates
  • SigningKey - secret key shared between your application and Calendly used to verify origin of incoming requests
  • CleanupAllExistingWebhooks - false (default) or true - if true, all existing webhook subscriptions will be removed from Calendly
  • SkipWebhookCreation - false (default) or true - if true, no webhook subscription will be created for given CallbackUrl
  • EventCreation - false (default) or true - if true, the webhook subscription will include event creation events

Remarks

Webhook subscription creation/removal will happen at the startup of your application thanks to an IHostedService worker. If both CleanupAllExistingWebhooks and SkipWebhookCreation are set to true the worker will not be registered with the DI container.

The dependency on Newtonsoft.Json allows (de)serializing custom enum member values.