Developer CertificationREST API

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 rooms in various formats (Raw text, MessageML).

Universal Webhook 2.0 or above is a managed service operated by Symphony in the cloud, and as a result is only available to cloud customers for now.

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 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 administrators can access the Symphony 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 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 Market 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 administrators via the extension application page.

Universal Webhook setup

Create a Symphony 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

  1. On the Symphony Admin Portal, select the APP MANAGEMENT tab, then click the Add Custom App button.

  1. Click the Import Application Bundle File button.

  1. Download the file below that corresponds to your environment, and then upload it in the Admin Portal to pre-fill all the fields:

Alternatively, create an extension app manually

  1. On the Symphony Admin Portal, select the APP MANAGEMENT tab, then click the Add Custom App button.

  2. Fill the text fields as follows :

  • Name: Universal Webhook 2.0

  • Publisher: Symphony

  • Icon URL: https://symphony_pod_loopback.com/apps/universal-webhook/default/assets/app-icon-square.svg

  • Description: 

    Share content and alerts from third party services in Symphony chats. 

The Universal webhook allows you to configure webhooks for Symphony, and provides a simple way for external apps and cloud services to share content in Symphony chats. It is often used to receive notifications and messages from the web, directly in your chats. 
Many popular services are compatible with this technology, such as Zapier, IFTTT, Jira, Jenkins, Datadog, Splunk, and more.
 
Universal Webhook 2.0 is a managed service operated by Symphony in the cloud, and as a result is only available to cloud customers for now. It replaces the legacy service that was delivered through the Integration Bridge.

  • RSA Public key (Production environments):

-----BEGIN PUBLIC KEY----------BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtE1qkejJr61d1KoBfu4qgELHhiBFNl98P7kqUnVL1FIH++Ur0vtU0wnZ5q94FGqLK2RZcBqvwuYyoshQ/k3fiDY9nLdtNWw2COJjnwmVMeh36QrvQ1c/mB0CAAZd+Q3hbzPJqFYS3jXqgmZPSU7Z391eiYi3wH5Zhvs93iRIXjIR6z78VqfbieN69PmbHPkn3fSzt2B0wQZhU9CoDHeucCPUujnGi+MeSDcMelMdW2nl32cyICfA+GhUZslrDBk2hkrYXwVmJDW6L3t92SattVNbUCH3SjEjbAQAbg1TXV+3AxTt9+rGZ6EglqY4AE8qvBPqcMBkc9lBUPNfjm+BPyqPkGWRXM3tMHejQgEJ5O2w/WIHDpWMqVyT/uX6nOm4rZOEoooveHAwBUhqfoYCAVp2BCFZCHgCKbzPz9cwq6CbRpTPvn37P2GVTjKQD+O2pgu8upcnqwn1NRZph+FSK8XetHF+9Yk4nQkJIyfuSu2diuo+P32BIhTqiNtweYlcBOO+1aLWlcSa+L6AztnqO9O/Wceg5h9B5eYRAApgmmsKaQ6U5FFOX+Npay5TNoM3Hwyq5zfNNd2D5U1MQmjL1th1z3qDDVuvcNJJmu4LgJxLql8N8FtQFP4ZqoplqcoG5f+YuS6Ch4UO/skrvIoKLHBZ/LXGkJoeVgby5OSqt60CAwEAAQ==-----END PUBLIC KEY-----

  • RSA Public key (UAT environments):

-----BEGIN PUBLIC KEY-----MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAwUkX6NzMYnE1gahhgFwk1jUffd0TclcqVN0AfRuGINiRpD2FA4s4ZfVtV9kRMLzz6uiiF+0r2TYNaM5XDbqzR+imf5PzJ2sIaoxVumSKZ1oHvnu865QwVMzMfJO4xQgybjqqruyztIs1hGMoaSTjOdlED6EuEq7XcP//ssGtG8+sDretkXqeTY3mtrcRFbK/praEoZpqnde3jjoTAYf2T8hwct4IU1FAyuP/WCK24bQMXrxurMe/3Y+5nYI5dzTH9IQ3bqXLTEXQIKB34tjVq782xdl4CKO9XjY+MY4qGMqJWeIvWsLc1QNJIccASbBg8fLdsG055btNcCQTs35g7NEvJIQ5kAPLGEo8DdjXJhjuXo8kcWovXB4B1vUws5jnBUZUW9s8d3J6zyXZHHRs9nZf9YlSwxlKCYTCxybkVvYE0PUxiSXqydprjE4TQR8HzSQlgsNNz/s1fV93Kppp2wvhOWJfbxQz55c4AHDC+04Jt8YRjZQjDwHFwp9FxiaWJ3JdPsXWgdQ1J7oSHx6coCeTARNE0JBKz4hvX5FMxe/4kg7T+NPOIIafE3IV8wRqkt3miSOiCwrf5weORi/5gK7hnRvJo+FxZSXfQLxnGos0NhHyMz/wTJTg04P+rvcU2rUlexSwo6sRRwbfpmLpzoC6MGlS2BUryeNm4GaRTxsCAwEAAQ==-----END PUBLIC KEY-----

  1. These two permissions must be granted to the application:

  • Act as user : Is required for the bot to access the user role in Symphony on behalf of the user (see below).

  • Business User Identity : Provides to the app the information of which roles the user has.

The end result should look like this:

Create a Symphony service account for Universal Webhook

Create a service account

In Symphony, you must configure a service account using the Admin Portal (or via API).

  1. Select the Create an Account tab.

  2. Select the Service Account tab.

  3. Fill in the mandatory Username, Display Name in the Service Account form.

  4. Set the Role in Symphony to Individual.

  5. Set the entitlement Can edit profile picture to Yes.

  6. 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.

openssl genrsa -out webhookbot_privatekey.pem 4096

openssl req -newkey rsa:4096 -x509 -key webhookbot_privatekey.pem -out         
           webhookbot_publickey.cer

openssl x509 -pubkey -noout -in webhookbot_publickey.cer >
            webhookbot_publickey.pem

cat webhookbot_publickey.pem

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).

  1. 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

  2. Enter Universal Webhook in the Search field to find the app you deployed in the steps above.

  3. 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 Market, 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

  1. Go to the ADMIN tab of the Universal Webhook extension app.

  2. Fill in the service account username as defined in the Symphony Admin Portal in the step Service account creation.

  3. Fill in the Service Account private key generated in the step RSA authentication configuration.

  4. 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 Admin Portal (username and public key), the update will be successful and the Universal Webhook will be usable.

Create and test a Webhook URL

  1. Add the Universal Webhook bot to a Symphony room (or directly open a direct chat with the Universal Webhook bot).

  2. Click the chat header button to create a webhook URL.

  1. Type in the details of your webhook URL.

  1. Fill in the details and click SAVE AND ACTIVATE.

  2. Copy your URL to test it.

If we target a messageML unauthenticated webhook, the curl command would be:

curl --location --request POST 'https://[tenant].symphony.com/universal-webhook/[id1]/[id2]/[id3]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'message=<messageML>test</messageML>'

If we create a raw unauthenticated webhook, that would be:

curl --location --request POST 'https://[tenant].symphony.com/universal-webhook/[id1]/[id2]/[id3]' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'message=test'

Have a look at the User guide for more information.

How to uninstall

To uninstall the Universal Webhook, please disable the configured extension app and deactivate the provisioned service user.

Last updated