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