Modules: Webhook

Let's look at building a Webhook to send data and files to other systems like Jira or Slack!

Chris Jones avatar
Written by Chris Jones
Updated over a week ago

The Send Data: Webhook Module is incredibly powerful!

Webhooks are great at passing on information and data from one application to another! This allows Enboarder to speak to other systems smoothly.


โ€‹Note: Setting up a Webhook module requires technical support from your IT team! โœ…

You might be wondering, โ€œWell, how can I use this module?โ€ Great question! Have a look at a few use cases below that you can explore. Also note, you can encrypt your Webhook Data as well, you know.. for that extra layer of #Security!

You can send an "A Bit About You" Form data from Enboarder to Slack to share information about your new hire with the team! Not only can you share the data, but if you ask your new hires to upload a selfie - you could send this to Slack too. ๐Ÿ˜Ž

Now that's true personalization at its finest.
โ€‹

Another example is sending the answers from a manager's IT Request Form from Enboarder to Jira or Service Now to help speed up that often-dreaded IT process.

Spoiler alert! check out the bottom part of the article to learn how to add Files to your webhooks.

Note: Before you begin the webhook process, you need to capture the data to update somewhere in that Workflow before adding the Webhook module.

For example, you can use a Form to capture the new data you want to send and then save it. Now you'll be able to create your very own webhook!

In the example below, let's send the employees 'A Bit About You' section to Slack.

Want to skip ahead? Check out the topics covered in this article below.


How to add a Webhook

Step 1: Start by clicking the โ€˜+โ€™ icon and selecting Webhook. This is where you can set up what data you want to send, and where that data is going.

Note: Donโ€™t forget to name & describe your Webhook module!

Step 2: The web-hook will be configured in 3 steps:

  1. Configure basic web-hook (Connect to API)

  2. Execute API with sample data (Select Employee information)

  3. Map response with Enboarder objects (Map to Enboarder fields)

Connect to API

You will need to enter the endpoint URL of the system that will be receiving the webhook, e.g. Slack or Jira. You will also need to choose the request method (POST, PUT or GET).

Use the dropdown menu for Authentication. Most commonly you will use Standard Authentication. Enboarder additionally supports OAuth for several popular systems too! If it isn't in our prebuilt tiles, you can create this yourself (check it out in this article). If you use Standard Authentication, you may need to include an API key in the Headers. Some systems also require additional Header Keys/Values. You can click the "+ Add More" button for as many Headers as needed.

The body section is where you can generate and customize a JSON payload if required by the receiving system. The button that says "<T> Insert Text '' allows you to include Dynamic tokens within your JSON payload editor such as a new hire's first name.

Enboarder will automatically populate these Dynamic tokens for each time the webhook is sent within a workflow.

If you do not want to map responses to fields in Enboarder, tick Skip response mapping and you can save the module.

If you are using POST method and have added tokens in the body (using the <T> Insert Text button), then please provide sample values to these tokens by clicking Map Sample Data.

Enboarder will show all tokens with a sample value, please review and update values as per your business needs and click save.

Once sample values are provided, the Test Connection and load information button will appear.

If the request method is GET or there are no dynamic tokens used, Enboarder will show Test Connection and load information button directly.

Once clicked, Enboarder will call the API URL configured with your payload. The system will replace dynamic tokens (if added) with the sample values that you provided.

NOTE: If you are using the POST method, once clicking Test Connection and load information, this will create a test record in the system you are sending data to. It's important to inform the system owner to expect this sample data.

Execute API with sample data (Select Employee information)

In this step, the system will show the response in a directory tree format. You can select which fields you want to map in the next steps.

  • Click on Select employee information

  • If the webhook has executed correctly, you will see the response in the below format:

In case of an error, Enboarder will show an error message on this same page.

You can now browse and select the fields which need to be mapped. Once fields are selected, click on step 3 to map these fields.

Map to Enboarder Fields

This is the last step where you will need to map these fields with Enboarder objects.

  • All selected fields from the response will show in the left column

  • You can map these fields with Enboarder fields using the right column

Once all fields are mapped, please save the module.

Once the workflow is launched and the sequence is executed, Enboarder will call the API with actual data and if the response is successful, the system will populate values from the response to mapped Enboarder fields.

Trouble Shooting

Please check integration logs to view the detailed results of webhook execution and response processing.

There will be two records in the integration logs:

  1. The bottom records provide details of the API call and its response.
    โ€‹

2. The top record provides the details of the response and its mapping, as well as the status of the API call to update the workflow and profile.


How to send files through Webhooks

We support file attachments in the webhook module as well!

Technical requirements

Ability to send an attachment in the below formats:

  • As a link with mime type and file name

  • As a base64 data with mime type, and name

  • As form data

UI Setup

Form setup:

There is no change necessary in the Form setup. You can attach the File by using the File upload widget in your Form.


Webhook setup

This guide will help you configure the endpoint URL of the destination system and any header request required by that API.

To configure your file attachment, use the below as an example:

Configuring JSON payload

Here the tokens used are from the Enboarder Form:

{

"file": "{{enb_func_file_link(form / upload_documents / uploadfile)}}",

"name": "{{account_name}}",

"candidate name": "{{newhire_firstname}}"

}

Explanation of file function :

The two types of functions we are supporting now are:

  • Add Base 64 data (Default)

  • Add link

Add base 64

Below, XXXXXXXX is a file attachment token added using the Insert text button. This is the default mode and will work even if the function is not used in the payload.

{{enb_func_file_base64(XXXXXXXX)}}

This function adds File as base64 in the below format:

{

"name": "Local CSR",

"candidate name": "Sammpy",

"file": {

"name": "WeChat-messagesend.jpg",

"mimetype": "image/jpeg",

"body": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/2wBDAQMDAwQDBAgEBAgQCwkLEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBD/wAARCAIzAosDASIAAhEBAxEB/8QAHQABAQADAQEBAQEAAAAAAAAAAAcFBggECQMCAf

/EAE8QAAAGAgECAgYHBgMGAgkDBQABAgMEBQYHEQgSEyEUGCJWl9UVFhcxV1iVIzI4QXe1CVFhGSQzQqbUN3ElNENTdoGFkbYmcrRSYnOSs//EABQBAQAAAAAAAAAAAAAAAAAAAAD/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwD6pgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/h11phs3XnUNoT96lKIiL/wCZj+wAAAAAAAAAAAAAAAAAAAAAAH896CWTZrLuMuSTz58AP6AAAAAAAAAAAAAAAAA"

}

}

Add link

Below, XXXXXXXX is file attachment token added using the insert text button:

{{enb_func_file_link(XXXXXXXX)}}

This function adds the File as a link in the below format:

{

"name": "Local CSR",

"candidate name": "Sammpy",

"file": {

"name": "WeChat-messagesend.jpg",

"mimetype": "image/jpeg",

"path": "https://localhost:9000/filedownload/attach?key=e61fbe495aa974bd9bf918150a4b03612687a16c291c5ecafbd0a2bac9463e367c1df36d8c5bcbd88b69c9599b7e57b1d2e741680577687eb78942e3d078a05c865e1ae7f98e4a885d5461ea36eb62588a4aa28a2fd35478bc430be5547b6f2fa44060f5acda81c7595f2b7885231b92cb7a0fe99920d6b9977e09b9d32213ab6e2e80d235b29cb7acfe95580ad794e260fb9c4431d17b4a6c7f429b11c8e7ab0b24b012c77f64923820328223c00879391438e82a945cd616819b54371185a6ecc27ebd2b8074aa604f571a8b1e51426125e3382dba217ee99c7eecefa9de23dd2d5701cd09ec9aba7787a99f78461398a60398c5c39b1f2f529c1df8f13873a8a25f129457fc0cf22885dfb449a368"

}

}

Send attachments as a multipart Form attachment

Want to send data as a multipart Form attachment?

Simply tick the โ€œConvert JSON to form-dataโ€ box and click save.

If you select this, we convert all form data and send it to the webhook configured. The file will be sent as multipart Data.

For example, If you want to add an attachment to Jira Issue using their API, you need to send info in the form data:

Method - POST

URL - {{Jira server URL }}/rest/api/3/issue/{issueIdOrKey}/attachments

Webhook Payload:

{

"file": "{{form / upload_documents / uploadfile}}",

}

That's it! All done.

Got questions? Start a chat with us by clicking the ? button in the top right of any Enboarder page if you have any questions about this.

Did this answer your question?