Integrating a Webhook with SESAR: everything you need to know

How do I integrate a Webhook with SESAR?

The SESAR webhook notifies your system when a file has been received and processed. It relies on an HTTP request containing a structured object and must be configured correctly to ensure seamless integration with your environment.

When a file is uploaded via SESAR, it sends a notification (a "hook") to an address you have defined. This notification contains an encrypted object, which must be received, decrypted and processed by your service.

Prerequisites

  • WebHookKey: 256-bit AES key, which can be generated with SECT Tools.
  • WebHookIv: 128-bit initialization vector (IV), which can also be generated with SECT Tools.
  • These two values are used to encrypt and decrypt the StoreManifests, and must be protected in your environment.
Warning: after the first startup of SESAR, these values are encrypted in a ".sesar" file specific to your configuration. This file must not be moved.

Step 1: Prepare the address that receives the webhook

  1. Publish on your server the endpoint that will receive the SESAR notifications.
  2. Give this endpoint a URL that follows the format https://[server_address]/[endpoint]/[method]
  3. Configure this endpoint to accept a POST request sent with the header Content-Type: application/json.

For example: https://localhost/Test.asmx/SESARHook

Step 2: Receive and read the notification

  1. Retrieve the body of the POST request sent by SESAR.
  2. Read the CryptedObject field: it contains the manifest encrypted in base64.
  3. Read the HashKey field: it contains the SHA512 of the public key used for encryption, also in base64.

The request body has the following form:

 {
 "args": {
 "CryptedObject": "...",
 "HashKey": "..."
 }
 }

Here are two examples of a C# implementation.

In ASMX

 [WebMethod]
 [ScriptMethod(UseHttpGet = false, ResponseFormat = ResponseFormat.Json)]
 public void SESARHook(SesarWebHook args)
 {
 // Traitement ici
 }

In ASP.NET MVC

[HttpPost]
 public string SESARHook([FromBody] HookArgs SEManifest)
 {
 var crypted = SEManifest.args.CryptedObject;
 var hash = SEManifest.args.HashKey;

 // Traitement ici
 return "OK";
 }

 public class HookArgs
 {
 public SesarWebHook args { get; set; }
 }

 public class SesarWebHook
 {
 public string CryptedObject { get; set; }
 public string HashKey { get; set; }
 }

Step 3: Decrypt the CryptedObject

  1. Use the Secure Exchanges SDK to decrypt the received object, the StoreManifest.
  2. Provide the 256-bit AES key in base64Key and the 128-bit initialization vector (IV) in base64Iv.
  3. Deserialize the result into a StoreManifest object.
 var jsonObject = CryptoHelper.DecryptStringFromBytes(
 Convert.FromBase64String(cryptedObject),
 Convert.FromBase64String(base64Key),
 Convert.FromBase64String(base64Iv)
 );

 StoreManifest manifest = SerializationHelper.DeserializeFromJson<StoreManifest>(jsonObject);

Troubleshooting

The webhook works according to the following rules:

  • The webhook is called every 30 seconds if files are available.
  • An HTTP 200 code means that the processing was successful.
  • If the webhook fails or returns another code, it will be retried.
  • The response waiting time is limited to 5 minutes.

Need help?

Our team is available to assist you. Write to us at support@secure-exchanges.com

    • Related Articles

    • What is SESAR?

      SESAR (Secure Exchanges Send And Receive) is a Windows service designed to integrate and secure your communications sent through Secure Exchanges, whether they are stored locally or in the cloud. It acts as a true vault for your data, which you ...

    • How do I install SESAR (Secure Exchanges Send And Received)?

      This simple and detailed guide walks you through the configuration and installation of SESAR (Secure Exchanges Send And Received). Prerequisites The machine on which SESAR will be installed must have the following specifications: Operating system: ...

    • How do I decrypt a message saved on SESAR using SECT Tool?

      Decrypting messages stored on SESAR can be done by following a series of simple steps using the SECT Tool. Here is a detailed guide to walk you through the process. Step 1: Prepare the files and open SECT Tool Open the unencrypted version of the ...

    • What are the configuration parameters for SESAR?

      Because SESAR operates on a tenant basis, an organization could have several tenants. The configuration file is therefore built so that the service is installed only once, but can retrieve the information of all the tenants. Each SESAR is an instance ...

    • What are some frequently asked questions about SESAR?

      SESAR is our local server designed to ensure complete synchronization of confidential communications. In this document, we answer frequently asked technical questions to help you better understand its operation and integration. Does SESAR work on ...