Installation guide
Overview
Universal Webhook is a Symphony Managed Service (operated by Symphony in the Cloud) that allows users to receive trusted or unauthenticated incoming webhooks within Symphony Messaging rooms in various formats (Raw text, MessageML).
Key benefits
Always receive your events with a Symphony managed service and track functional errors as they occur thanks to a detailed Webhook History.
Receive payload in raw text or in MessageML for complex messages.
Action workflows from client applications or bot room members.
Control the security level of incoming webhooks thanks to various authentication schemes.
High-level admin flow
The Symphony Messaging administrator first needs to set up a service account that is going to be used to post the messages into the rooms. That user might already exist; in this case the private key of that service account will be needed in order to link the service account with the Universal Webhook service.
Symphony Messaging administrators can access the Symphony Messaging application called Universal Webhook. All users can access the application, but only Symphony administrators can access the setup tab in order to set up the service account to be used. The Symphony Messaging admin will need to provide the service account username and private key to successfully set up the Universal Webhook service.
High-level user flow
Users can install the Universal Webhook extension application from the Symphony Messaging Marketplace to create webhook URLs.
Once the application is installed, users can create webhook URLs in rooms they are owners of via the extension application chat header button. They can then use those URLs in their source applications to send messages to those rooms.
When a payload is received from the source application on a webhook URL, the Universal Webhook checks if the authentication details are correct and tries to send the message to the room corresponding to the webhook URL via the Agent.
Message authentication, delivery successes, and errors are logged in the webhook history accessible to room members (via the extension application chat header button) and the Symphony Messaging administrators via the extension application page.
Universal Webhook setup
Create a Symphony Messaging extension app
Your Symphony technical point of contact (Technical Account Manager, or Solutions Architect) is in a position to perform this step for you. If you do not have a point of contact or you wish to do this step yourself, follow the instructions below.
Create an extension app by importing a JSON file
On the Symphony Messaging Admin Portal, select the APP MANAGEMENT tab, then click the Add Custom App button.
Click the Import Application Bundle File button.
Download the file below that corresponds to your environment, and then upload it in the Admin Portal to pre-fill all the fields:
The end result should look like this:
Create a Symphony Messaging service account for Universal Webhook
Create a service account
In SymphonyMessaging , you must configure a service account using the Admin Portal (or via API).
Select the Create an Account tab.
Select the Service Account tab.
Fill in the mandatory Username, Display Name in the Service Account form.
Set the Role in Symphony Messaging to Individual.
Set the entitlement Can edit profile picture to Yes.
Select Create.
Configure the RSA authentication
RSA is an asymmetric cryptographic system that leverages a public and private key allowing any user with the public key to generate a message that will be decrypted with the private key.
In order to use RSA for authentication, you must generate a key pair using OpenSSL.
Once generated, the private key must be accessible to configure the Universal Webhook service.
Should any part of the RSA key be lost, it can be regenerated and you can update the service account with the new one.
Configure the service account with the RSA public key
The public key needs to be set in the Symphony service account via the Admin Portal (or via API).
Copy and paste the contents of webhook_publickey.pem.
Set your public key
Link the service account with the Universal Webhook service
Load the Universal Webhook app in Symphony Messaging
Enter Universal Webhook in the Search field to find the app you deployed in the steps above.
Select Install, then Open to launch the application.
You will see the app landing page and the available ADMIN tab next to the OVERVIEW tab.
If the application does not appear in the Symphony Messaging Marketplace, check the developer tools for errors. An incorrect URL or untrusted web server certificate are common errors.
Set up the service account on the Universal Webhook service
Go to the ADMIN tab of the Universal Webhook extension app.
Click on UPDATE.
Optionally, explicitly allow unauthenticated webhooks to be created. Otherwise the only webhooks that will be processed will be the ones using a pre-configured HMAC secret or Shared secret in the header.
Optionally, the administrator can update the Universal Webhook picture directly from the extension application by hovering on the avatar placeholder.
If the service account username and private key match what is defined on the Symphony Messaging Admin Portal (username and public key), the update will be successful and the Universal Webhook will be usable.
Create and test a Webhook URL
Add the Universal Webhook bot to a Symphony Messaging room (or directly open a direct chat with the Universal Webhook bot).
Click the chat header button to create a webhook URL.
Type in the details of your webhook URL.
Fill in the details and click SAVE AND ACTIVATE.
Copy your URL to test it.
If we target a messageML unauthenticated webhook, the curl command would be:
If we create a raw unauthenticated webhook, that would be:
How to uninstall
To uninstall the Universal Webhook, please disable the configured extension app and deactivate the provisioned service user.
Last updated
Was this helpful?
