Table of Contents

SESAR Webhook

Automatically receive in your systems what SESAR drops in your vault: CRM, SharePoint, Dynamics 365, file storage or your own API.

SESAR Webhook is a .NET web application that you host on a Windows server. Secure Exchanges provides it as reference projects on GitHub, with their source code: you build, configure and deploy it yourself.

Project Platform
SESARWebhookCore .NET 9 (ASP.NET Core), recommended
SESARWebhook .NET Framework 4.7.2 (ASP.NET Web API 2), on IIS

This help center documents the .NET version. For the .NET Framework version, see Choose your version.

How it works

  1. For each drop in your vault, SESAR sends a POST request to the webhook address you configured. The body contains the drop's manifest, encrypted, and an authentication value (HashKey).
  2. The webhook checks this value, then decrypts the manifest with the key and initialization vector it shares with SESAR.
  3. It passes the manifest to the connector or handler that the called address designates.
  4. The connector or handler sends the data to your system, then the webhook answers SESAR. Only an HTTP 200 response counts as a confirmation: otherwise, SESAR sends the request again later.

What the manifest contains

The manifest (StoreManifest) describes the drop: subject, recipients, file names, sizes and hashes, file paths on the SESAR server, callback parameters and signature data.

Callback parameters are the most reliable way to file each drop in the right place: the identifier that your application attaches when sending, such as a case number, comes back in the manifest. See Classify drops.

The files themselves do not travel in the request: only their paths do. A connector that must read the files therefore has to run on a machine with access to SESAR's storage.

Handler or connector

The webhook receives SESAR's call, checks it and decrypts the manifest, but it does not know where to send the data. That job belongs to a piece of code that receives the decrypted manifest and sends it to your system: a handler or a connector. Both do the same job; they differ in where their code lives.

  • A handler is your own code, in a separate DLL that you drop in the handlers folder. The webhook loads it at startup, like an extension: you do not touch the webhook.
  • A built-in connector is compiled into the webhook application, like a feature shipped with it. Adding or changing one requires changing the webhook's source code, then rebuilding and redeploying it.
Handler (recommended) Built-in connector
For Your own business logic The examples provided with the project
Form A DLL with a class that inherits from WebhookHandlerBase, dropped in the handlers folder A class compiled into the application
Address called by SESAR /api/webhook/handler/{id} /api/webhook/{id}
Setup Copy the DLL, restart the application Edit Program.cs, rebuild, redeploy

The path of a drop with a handler

  1. SESAR sends the drop to https://<server>/api/webhook/handler/my-cases.
  2. The webhook checks the call and decrypts the manifest.
  3. It calls the my-cases handler, passing it the manifest.
  4. The handler extracts what it needs (subject, recipients, number of files) and calls your system's API.
  5. It returns a successful or failed result.
  6. The webhook answers 200 to SESAR if the processing succeeded. Otherwise, SESAR will send the drop again later.

Why prefer a handler

  • It survives webhook updates: your changes do not have to be merged back into its source code.
  • It deploys simply: you copy a DLL and restart, without rebuilding the webhook.

The built-in connector remains useful if you maintain your own version of the webhook, or to start directly from a provided example. In code, a handler inherits from WebhookHandlerBase, and a connector implements IIntegrationConnector. See Create a handler.

The four connectors provided, File system, Zoho CRM, SharePoint Online and Dynamics 365, are examples to adapt. Read their page before using them: they are not production-ready as is.

Prerequisites

  • A Windows server: the application protects its secrets with DPAPI, which is specific to Windows.
  • The ASP.NET Core 9 runtime, or the ASP.NET Core 9 Hosting Bundle on IIS.
  • An HTTPS address reachable by SESAR, with a certificate that the SESAR machine trusts.
  • The webhook key and initialization vector, defined in the SESAR configuration.

Where to start

  1. Choose your version
  2. Quick start
  3. Secure the deployment, to read before any production use