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.
- Click the System Parameters link from the Main Menu. The System Parameters page opens.
- Select parameter AA (application) 496 (code).
- Right-click and select Edit. The Edit System Parameter window opens.
- Enter a Y into the Alphanumeric Value field.
- Click OK.
Creating webhooks requires two steps:
Configure the Webhook
- Click the Webhooks link from the Main Menu. The Webhooks page opens.
- Click the Add button. The Add Webhook window opens.
- 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.
- 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);
}
}
}
Comments
19 comments
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
Currently it is shipped in the v20 \bin folder.
-1 upvotes
Thanks Craig. I'm using a hosted SAAS solution so I don't have access to any v20\bin folder.
0 upvotes
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
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
Andrew - Yes, that is the correct object to use.
0 upvotes
Seems like it is still not on nuget? I have lodged a ticket to have to get it.
0 upvotes
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
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
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
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
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
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
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
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
Hi Hannes,
This is being discussed internally and I'll update this thread when I have an answer for you.
Thanks!
Maggie
1 upvotes
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
Hello,
We are currently using the encryption option for the webhooks, but there is no information on decrypting the payload.
We have found an old DLL that contains logic for decrypting the encrypted webhook. The class in the DLL is Ungerboeck.SDK.WebhookServer. The DLL looks to be over 6 years old, and we are wondering if there is more recent package for the decryption?
Any help would be much appreciated.
Regards,
Eric
1 upvotes
Hi Eric,
I recommend not using the encryption option due to the complexity. The combination of https and the secret should be secure enough, and we are currently redesigning the encryption field as well as the distributed webhook SDK.
Regards,
Rudy
0 upvotes
Please sign in to leave a comment.