User guide

Setting up a new webhook in a chat room

1. First, add the Universal Webhook bot into the chat room, by clicking Add members at the top of the chat room, then searching for Universal Webhook.

1. Once the bot is in the chat, click on the Universal Webhook button that appeared in the header of the chat room, as visible below:

1. A modal window opens that lists the webhooks already configured for this chat. Now, select Add a webhook.

1. Add a name for your webhook. Anything will do - this is so you can identify the webhook later.

2. In the Integrated service field, indicate which service will be sending data to Symphony Messaging.

1. Select whether the service will send Raw Text, MessageML v2 (Symphony Messaging's markup language), or a JSON object in the Webhook type field.

You can find the specifications of the MessageML v2 under the following link: MessageML v2 Specifications.

Also, note that your webhooks can contain attachments for any type you choose. This particular case is addressed at the end of this page.

Testing a JSON mapping

If your service sends a JSON object, you will need to provide a template for mapping the JSON data to a readable format.

1. Enter your template and a sample of JSON data.

2. Click Test to see how your message will render.

If your message is valid, the bot will send you the message in a direct chat. If not, an error message will advise you why your template or data is not valid.

Authentication

Unauthenticated webhooks

In the Security type field, you can choose the security protocol that validates the incoming data.

If your Symphony Messaging Admin has permitted it, you will have an option for Unauthenticated Webhooks. In this case, incoming data will not be validated.

Symphony recommends using a security protocol to validate the data, even if you are not required to do so.

Shared Secret authentication

If you choose 'Shared Secret,' your data will require a secret to be sent along with it under a custom header.

1. Choose a custom header for your webhook. Any data sent without this header will be rejected.

2. Enter a secret value. Universal Webhook will match this value with the value under the header you chose above to validate your webhook data.

HMAC Secret authentication

If you choose 'HMAC Secret,' your data will require a secret to be sent along with it under a custom header. The value of the secret header will however be a hash that will be depend both on the content of the payload as well as on the pre-configured secret.

More precisely, Universal Webhook will use the HMAC SHA256 algorithm to compute a hash from the payload of your message and the secret key. Then it will match the result with the value of the custom header received in the webhook, which you will have also computed before sending in a similar way.

If the values don't match, then the data will be rejected.

1. Choose a custom header to use for your webhook. The custom header name needs to be lower case only. Any data sent without this header will be rejected. Let's use "authorisation" for our example.

2. Enter a secret value. Let's use "this is my secret"

3. Build the text to be hashed: Take the value of the message property, remove the <messageML> tags, then wrap it in a JSON payload property:

   • For example message <messageML>Hello world!</messageML> would become {"payload":{"message":"Hello world!"}}

4. Using the HMAC SHA256 hash function, compute a hash of the text above using the secret "this is my secret" as secret key.

   • Using the sample secret defined above, you should obtain the following hash 8de567399a49f3ed91ed55435c0887c7c935413e01cbd7a2ac06dab1b04cc1c6

5. Send the request to the webhook URL and specify in the http headers the custom header and the computed hash as value:

6. 
7. Universal Webhook will perform the same steps, compute the hash and compare it with the provided hash. If the values match, the message will be sent in the chat room.

Integrating with your service

1. Click Save and activate to create your webhook.

2. Copy the provided URL and enter it where it is needed in your service's settings.

Example with Postman

Consider this sample setup using Shared Secret validation.

1. Fill in the fields and click Save and Activate.

2. Copy the generated URI to provide to the service that will send data to the webhook.

1. In Postman, create a new POST method and paste in the URI.

1. In the Headers, enter the Shared Secret Header and the Secret to match the values from the webhook setup.

1. In the Body, enter a raw text or MessageML v2 message to send, then click the Send button.

After a moment, you should see a '200 OK' success indicator in Postman.

And in Symphony Messaging, Universal Webhook delivers your message.

View your webhooks

Now, when you open the Universal Webhook Modal, all of the webhooks for the room will appear in a list.

From this list, you can deactivate, edit, or delete a webhook. Webhooks must be activated in order to work.

If you hover over the webhook name, an icon will appear.

• Click this icon to copy the webhook URL to your clipboard.

• Click the webhook name to show the webhook history.

View your webhook history

The webhook history view shows a high-level view of your webhook information, but doesn't expose your security secrets.

You are able to see all accepted and rejected requests over the last month. Filters will allow you to limit which requests you see.

• Click any item in the list of requests to expand it so you can see more information.

• Click the item again to collapse.

Send attachments in Symphony Messaging

To attach files to a webhook, set theContent-Type header to multipart/form-data and add the attachments in theattachment field. You can also include a preview of the files that will be displayed directly in the chat conversation, using the preview field.

The way to attach files depends on the type of webhook used (MessageML v2, Raw text, or JSON). An example of each type is available below.

MessageML example

Example of a MessageML webhook with a file attached, in Postman.

Raw text example

Despite the webhook being of type Raw text, please continue to set the content type to multipart/form-data, as you can see in the following example.

JSON example

With a JSON webhook, the message data needs to be added to the data field.

Example in Postman:

Example in cURL:

curl --location 'https://corporate.symphony.com/universal-webhook/041daxxxxxxxc4eXYZ' \
--header 'secret: thisismysecret' \
--form 'data="{\"mydata\":\"This is a message\"}"' \
--form 'attachment=@"/C:/Users/pierre.neu/Downloads/image (19).png"'

Corresponding JSON template:

<messageML>
  ${entity['mydata']}
</messageML>

Adding preview of the files

Postman request sample of MessageML v2 type with an attachment and its preview:

Display of the resulting message in a chat:

Limits of attachments

Attachments are subject to the following limits:

• Max size of 25Mb;

• It is recommended not to exceed 25 files;

• It is possible to use a preview with the attachment; please note that an error will be returned if the number of previews doesn't match the number of attachments if any preview is present in a webhook;

• You might get an error if you try to send attachments which type is not supported by your pod.