Webhooks are a development pattern that let you add custom logic to interact with or react to pre-defined business processes. You can use webhooks to create extensions and interfaces that extend the software to fit your business processes and the environment. Some examples are:
- New integrations - If the function date/time or location changes, send a tweet through Twitter.
- New features - Send out custom emails when an invoice in generated or create a change notification system.
- Custom validation - Validate account data to adhere to your organization’s standard. If you have a free-form text field users need to complete in a specific way, you can ensure this is done when adding an account (or an event or any other webhook enabled subject).
The possibilities are endless!
To decide if you could use webhooks, consider what other processes occur outside of the software when you add/edit/delete something within the application.
Webhooks Overview
Webhooks are calls made from the software to a third party RESTful web service endpoint when specific events in the software business logic happen. For a supported subject like an event or an account, there are two points in the business logic where webhook calls are made:
- Validation – A call is made to a custom endpoint to validate that the entered date for the subject passes the custom validation that you implemented. This is a way for you to inject your own validation rules prior to committing to the database.
- Post-commit - This call is made after the change to the subject is successfully saved into the database at the end of the software process.
You must configure and activate webhooks to make webhook calls. This does require configuration.
Validation Webhooks
Validation webhook calls are made after the validation logic is complete. You can inject your own rules using a validation webhook. The data for the given subject is passed to the webhook endpoint for validation. The process following the call depends on the response sent back from the webhook.
- Successful validation - If the data passes the custom validation process, the save process continues to completion.
- Failed validation - If the data fails the custom validation, an appropriate message is sent back to the software, and the save process is aborted.
- Error Case – If the custom validation results in an error, the save process is stopped, and an appropriate message is displayed to the user.
- Timeout Case – The custom validation endpoint is expected to return the response in a set configurable timeout duration. If no response is received the save process is aborted, and the user is notified.
For example, you configure a custom implementation for the account validation webhook. In this case, you want to make sure every account that is added has an email address with the domain .uk, and an appropriate message is sent back from the webhook handler when the validation fails. When the validation fails, the changes the user made are not saved, and a business validation failed message is displayed as provided by the webhook handler.
Post-Commit Webhooks
Post-commit webhook calls are made once a subject in the software is added, modified or deleted. Post-commit webhooks are typically used to replace traditional database triggers to perform an action in sync with the changes happening in the software. You can configure the post-commit webhooks as synchronous or asynchronous. In the synchronous mode, the software waits for the response from the receiver and displays it to the user if the user interface allows for it.
The data sent for post-commit webhooks differs based on the type of event that created the notification.
- Record Added - You can only use the primary key values to lookup the record details are sent in the notification.
- Record Modified - The values that changed, including the original values before the values changed, are sent along with the primary key in the notification.
- Record Deleted - The entire set of values on the record are provided in the notification since the record does not exist in the software any longer.
Using a synchronous event webhook as an example, you want to notify registrants if dates on the event change. The custom application updates all registrants of the change to the event dates via SMS (text message). Once the event coordinator changes the event date, the custom implementation receives the notification and immediately sends all the registrants a text message to communicate the changes. The custom application then notifies the event coordinator that it is done sending text messages, and the user in the software receives a message notifying them that all registrants were notified of the change.
Comments
16 comments
Hello,
Two questions:
1. Is the API needed to send the error/alert messages back to the UI?
2. Can I use a validation webhook to issue an alert message when the existing value of a parent UDF is changed? And if yes: how?! Use case: since changing the value of a parent UDF erases the values from all child UDFs (with no way to undo), I'd like to have an alert pop-up when an existing parent UDF value is changed, warning the user that having done so erased all child UDF values, giving the user a change to re-consider and cancel the change.
Thank you,
Zak.
0 upvotes
Hi Zak,
Thanks for the questions.
Using webhooks is not tied to the API module, so the API is not needed when consuming webhooks.
As far as your use-case with UDFs and giving the user a chance to cancel out of the save process... We do not currently support raising a question to the user through webhooks. Currently you can return a value of Success or Error. Success lets the process continue and Error stops the save process and will return an error message that was provided by the consumer of the webhook.
That said, I do think this is an idea for Ungerboeck to consider. I've added an enhancement case to the team's backlog.
Thanks,
Craig
0 upvotes
Thanks, Craig.
So the error message that's currently supported can only provide a hard stop to the save process until the "error" is resolved, and no way to act more like an alert that prevents the first save attempt but lets a second attempt go thru without having to make any corrections?
Zak.
0 upvotes
Zak,
Yes, you are correct. It is a hard stop.
Thanks,
Craig
0 upvotes
is there a repository of commonly used webhooks? Id like to add one that alerts users that an event has been cancelled - would seem fairly standard. thx!
0 upvotes
Hi Michele,
I'm checking with our technical team about a web hook repository but in regards to the event cancellation alert, you could assign a recipient list to an automatic note that gets created when the event is cancelled - https://supportcenter.ungerboeck.com/hc/en-us/articles/213800968.
That may be easier if the recipients are Ungerboeck users but wouldn't work for non-Ungerboeck users.
Thanks,
Maggie
0 upvotes
Hi Michele,
My technical team got back to me on the repository question:
Webhooks are just notifiers. Ungerboeck sends a notification to where you tell it to go. However, something must exist at the URL you give it to “catch” the webhook and do something with the information it is sent. There are some services where you can do this without programming, like Microsoft Flow, but they do still require an understanding of how a web request works and need some thought put into the logic. Otherwise, you have to be or have a programmer to write something to catch the request.
This specific request is a standard use of webhooks but behind the scenes something different needs to happen for each organization (e.g. what mail address, mail server). So we can’t offer a solution in a webhook "library."
So in short, no, there are no standard webhooks because webhooks on their own don’t do anything.
Ungerboeck can always offer consulting assistance if you would like to try to use Microsoft Flow or a similar service to catch the request.
Thanks!
Maggie
0 upvotes
Hi Michele, did you see my post over https://supportcenter.ungerboeck.com/hc/en-us/community/posts/360036419933-Advanced-Validation-and-Webhooks
If we get a few more people on board we will look to build a service with common hooks and some simple mechanism for creating new/custom rules.
Hopefully this would be beneficial to you.
Thanks
L
0 upvotes
I have written a receiver API for the Account Updated webhook.
It fires successfully when I create a new account or update an existing account.
However when I merge two accounts, the webhook does not fire. I was expecting to see it fire once for the account that is updated (merged into) and once for the account that is deleted (merged from).
Please can someone explain why the webhook would not fire in this case. Or am I doing something wrong?
Thank you in advance.
0 upvotes
Hi Phil, the merge process uses a different process than the add/edit account process which is why the webhook doesn’t fire but it’s something we can take under advisement and review and discuss. You might want to post the request of the webhook for merge accounts to the CRM Product Idea forum to see if other users would find this useful or not. It's a great way to get votes on ideas and get them in front of project management.
0 upvotes
It appears that Webhooks do not fire if orders are generated in v19 or iEBMS pages. We're of course looking at migrating to the cloud for v30, but I was hoping to start switching our processes over to webhooks and the API from our old SQL triggers. The "Membership Order Updated" trigger action for instance works fine when testing and editing orders in v20, but does nothing if our members pay their dues online (MBD).
Unless there's something wrong with the config of our system. The AA 496 organization parameter for instance says... 'Y/N' Bundle a Work Order Report and its Attachments as one PDF file, then bundle all of them into one print job and print it to the default printer!
Seeing as v19/20.94 is no longer supported, I'm sure our only real option is to use v20 instead and setup the equivalent v20 web payment pages for members to pay their annual dues online. Figured mentioning anyway though, in case there's something simple that I'm just missing.
0 upvotes
That's correct Mark, they only fire in v20/v30 and v20/v30 customer facing web applications. Not in v19 or v19 iEBMS.
1 upvotes
Thanks for confirming Lee. I'm making some progress with the API and will either use SQL triggers to send emails to Power Automate and trigger the process that way, or just run the API query every 5 minutes or so and check for new orders. Then once we're exclusively using v20/v30 it shouldn't be difficult to adjust the processes to work with the webhooks instead.
0 upvotes
We are using the Account Updated webhook in v20.96, but it always passes GenderID as null.
When I use the Ungerboeck API - GET Accounts - I can see accounts with "Gender": "M" and "GenderID": 1, but when I update the account in USI Back Office, it fires the Account Updated webhook and passes GenderID as null.
0 upvotes
Hi Phil,
Can you update your SDK using Nuget to reflect the new model? I think you may be using an outdated version which is causing the problem.
Thanks,
Maggie
0 upvotes
Thanks Maggie. I thought I was using the latest SDK, but clearly I wasn't.
All good now.
0 upvotes
Please sign in to leave a comment.