Getting Started with Webhooks

This article guides you through how to enable webhooks, configure a particular webhook, and create code to handle the notification from the webhook. See Webhooks Overview and Webhooks in Momentus Enterprise for more information if you are new to webhooks.

Before you can begin using webhooks, you need to enable them. You only need to do this one time.

  1. Click the System Parameters link from the Main Menu. The System Parameters page opens.
  2. Select parameter AA (application) 496 (code).
  3. Right-click and select Edit. The Edit System Parameter window opens.
  4. Enter a Y into the Alphanumeric Value field.
  5. Click OK.

Creating webhooks requires two steps:

  1. Configure the Webhook
  2. Create the Webhook Receiver

Configure the Webhook

  1. Click the Webhooks link from the Main Menu. The Webhooks page opens.
  2. Click the Add button. The Add Webhook window opens.
  3. Enter the necessary information:
    • Description - Name for the webhook.
    • Web Service URL - Endpoint that handles the HTTP POST request when the Trigger Action occurs. Best Practice: Use secure URLs (https) for production environments.
    • Trigger Action - Action that causes the webhook to initiate. 
    • Is Asynchronous - If checked, the webhook is asynchronous and does not block business processing. If unchecked, the webhook is synchronous and blocks business processing until a response is returned.  
    • Status - Only active webhooks are used.
    • Ignore for API - If checked, the webhook is not initiated as a result of API calls. For example, if you configure a webhook for Account Update and within the webhook handler, you call the Accounts API endpoint, this could create an endless loop. If you configure the webhook with Ignore for API, the webhook does not initiate and you avoid the endless loop.
    • Encryption Key (optional) - Encryption key, if applicable. Note that HTTPs is already necessary for webhook notifications, so this is just an extra layer of encryption
    • Secret Key - Unique key that the custom web service uses to authenticate the request it receives. This is auto generated with random values.
    • Timeout - Time the software waits for the receiver’s response before terminating the connection due to timeout. The default is 15 seconds. You can increase this based on your requirements.
  4. Click OK.

You can now add a receiver at a location that matches the one configured when adding a webhook.

Create the Webhook Receiver

We recommend using an ASP.NET Web API project to create a receiver for webhooks in this article (when using Microsoft .NET) but you can use other web technologies to implement a receiver.

 

If you are using .Net, we also recommend using the following packages using Nuget package manager.

  • Newtonsoft - Allows for deserialization of generic JSON objects
  • Ungerboeck.Api.Models - Has pre-made models from Momentus Enterprise

 

An example receiver for the "Account Affiliations Updated" webhook notification is provided below:

Using a Web API ASP.NET project - Add a controller:

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using System.Diagnostics;
using Ungerboeck.Api.Models.Subjects;

public class WebhooksController : ApiController
{
   private const string SecretKey = "6ee56e4e-9209-4fa3-b52f-efb5f9b4adce";

   [Route("webhooks/accountupdated")]
       

   void GenericWebhookReceiver(object value)
   {
     const string SecretKey = "6ee56e4e-9209-4fa3-b52f-efb5f9b4adce";

     try
     {
       // Parse the JSON string to a JObject
       var webhook = JObject.FromObject(value);

       string secretKeyFromWebhook = ExtractProperty<string>(webhook, "SecretKey");

       //SecretKey from the notification should always be checked for security.
       if (secretKeyFromWebhook != SecretKey)
       { 
         throw new UnauthorizedAccessException("The webhook request is not authorized."); 
       }

       string hostUrl = ExtractProperty<string>(webhook, "HostUrl"); //Extract the webhook object properties
       
       //This expects an AccountAffiliationModel in the webhook data, but you can swap it with any available API Model type
       AccountAffiliationsModel propertyValue = ExtractProperty<AccountAffiliationsModel>(jsonObject, "Data");

       // Call a function to extract the property value
       AccountAffiliationsModel model = ExtractProperty<AccountAffiliationsModel>(jsonObject, "Data");


       Trace.WriteLine($"Incoming webhook from host URL {hostUrl}");
       Trace.WriteLine($"webhook received in GenericValidation, Account Code {model.AccountCode} updated");
     }
     catch (Exception ex){
       Trace.WriteLine($"trace - {ex.Message}");
     }
   }

   static T ExtractProperty<T>(JObject jsonObject, string propertyName)
   {
     if (jsonObject.TryGetValue(propertyName, out JToken valueToken))
     {
       try
       {
          // Use the JToken.ToObject method to convert the value to the specified type
          return valueToken.ToObject<T>();
       }
       catch (JsonReaderException)
       {
         // Handle a parsing error or type mismatch here if needed
         throw new InvalidCastException($"The value of '{propertyName}' is not of type {typeof(T)}");
       } 
     }
     else
     {
       // Handle the case where the property doesn't exist or is null
       return default(T);
     }
   }
}

Related articles

Comments

17 comments

Date Votes
  • Josh Green

    Where does one get the Ungerboeck Integrations SDK?  It doesn't seem to be on nuget.org?  The API SDK is but not the Webhook SDK

    0 upvotes

  • Craig Dudenhoeffer

    Currently it is shipped in the v20 \bin folder. 

    -1 upvotes

  • Josh Green

    Thanks Craig.  I'm using a hosted SAAS solution so I don't have access to any v20\bin folder.

    0 upvotes

  • Craig Dudenhoeffer

    For now, can you enter a support ticket?  We can get you those files through that process.  We still have a few things to work out before getting it into NuGet.

    0 upvotes

  • Andrew Grant

    I have the Ungerboeck Integrations SDK installed, but there is no AccountUpdatedDTO that is used in the example above. There is only AccountDTO. Is this the correct object to use?

    0 upvotes

  • Craig Dudenhoeffer

    Andrew -  Yes, that is the correct object to use.  

    0 upvotes

  • Kieron Marshall

    Seems like it is still not on nuget? I have lodged a ticket to have to get it.

     

     

     

    0 upvotes

  • Phil barker

    We have just set up a web hook receiver and can see that our API is being triggered by AccountUpdated over HTTPS.

    However, the webhook is not sending any data to the API.

    Are there any other steps that we need to follow other than those outlined above?

    0 upvotes

  • Lee Tickett (Tickett Enterprises Limited)

    Hi Phil, i've not experienced this before. Maybe try pointing Ungerboeck at RequestBin to confirm it's not an issue with your receiver?

    0 upvotes

  • Phil barker

    Thanks for your reply Lee.

    Apologies for my ignorance but I didn't even know that RequestBin existed.

    I had been trying to trace the web requests using Fiddler, but without any success.

    I'll try RequestBin and let you know ...

    0 upvotes

  • Cristina Pueyo
     

    What data send Update Account's webhook? 

    Will send data on json format?

    Wich is the AccountDTO structure?

    I've got a simple controller make it on spring/java

    @PostMapping("/updateAccount")
    @ResponseBody
    public void testWebHook(String body){

        LOGGER.info("[TEST WEBHOOK] {}", body);
    }

    But on server I get this

    0 upvotes

  • Maggie U.

    Hi,

    Webhooks in Ungerboeck communicate using DTO’s (Data Transport Objects). We have a defined structure for each of the DTO that belong to a subject. For example, AccountDTO.

    All the DTO’s are created from the respective data models defined in UngerboeckSDKPackage for each subject. You will need Ungerboeck Integrations SDK to create these DTO’s.

    You should create the DTO using the Ungerboeck Integrations SDK. It should then be converted to JSON format before sending to the webhook. You don’t need to know the DTO/Model structure to use webhooks but below is the AllAccountsModel for reference.

    Hope this helps!

    Thanks,

    Maggie

    1 upvotes

  • Hannes Eklund

    How should I make sure I have the latest/correct version of Ungerboeck Integrations SDK ?

    Only place I find it now is as Ungerboeck.Integrations.dll in bin folder in our 20.96 onprem installation.

    But I'm developing for v30.97, and obviously in the future we wont have an onprem installation (with a bin folder), even if the 20.96 dll is correct for use with 30.97...

    0 upvotes

  • Kieron Marshall

    You can see here for the SDK
    https://www.nuget.org/packages/Ungerboeck2096SDK/

    And the sdk Wrapper 
    https://www.nuget.org/packages/Ungerboeck2096SDKWrapper/

    1 upvotes

  • Hannes Eklund

    Thanks Kieron, but the SDK and SDKWrapper only contains code for the API, not the "Ungerboeck Integrations SDK" needed for webhooks, containing the DTO classes like AccountDTO used in the example in this article (Ungerboeck.Integrations.Webhooks namespace).

    I only find those classes in the Ungerboeck.Integrations.dll in the bin folder as stated above.

     

    1 upvotes

  • Maggie U.

    Hi Hannes,

    This is being discussed internally and I'll update this thread when I have an answer for you.

    Thanks!

    Maggie

    1 upvotes

  • Jeroen Tuinenburg

    Hello,

    I’m fairly new (noob) in building API’s in MS Visual studio 2019 ASP.NET Framework Web Application.

    When I’m trying to get the USI example Webhook controller code to compile, I’ll get an error as shown beneath.

    if (value.SecretKey != SecretKey) gives an error:

    Error      CS0012 The type 'AllAccountsModel' is defined in an assembly that is not referenced. You must add a reference to assembly 'UngerboeckSDKPackage, Version=20.9.5.0, Culture=neutral, PublicKeyToken=null'.

    However, I have all available Ungeboeck NuGet packes installed. (But can’t install one with version 20.9.5.0).

    And is available under “References”:

    Am I doing something wrong or is this a bug? Can someone please help?

    Thanks!

    Best Regards, Jeroen

    1 upvotes

Please sign in to leave a comment.