Create webhook listeners

This article provides a conceptual overview of webhook technology as it relates to integrator.io and includes the steps necessary to create listeners in your flow.

Contents

• Understanding webhooks
• Create a webhook listener (current UI)
• Create a webhook listener (legacy UI)
• Demonstration video

Understanding webhooks

Hooks are functions that can execute when a given event occurs. Webhooks are also hooks, but they can send an HTTP POST message over the web in real-time to a specified URL endpoint when a given event occurs in an application. The source application sends the message to a URL available to another system's webhook listener. The webhook listener receives the message and executes operations according to the message's content.

Before webhook technology was available, if you wanted to sync information in two places across the web, one system would have to send repeating poll messages to review the status of the data in the system it needed to retrieve new information from, and then update data based on the responses to the poll requests. Webhook technology eliminates the necessity for constant polling by allowing one system to automatically send a notification and all relevant information of a given change to another system as soon as the change occurs.

integrator.io supports webhook technology on source application exports. If you set up webhook settings within the user interface of your source application, you can configure listeners in integrator.io to receive messages from the source app and trigger integration flows based on the message content. Setting up webhooks for integrator.io requires two steps:

1. Configure a webhook in the source application for an event that triggers the HTTP POST message from the source application to integrator.io.
2. Create a webhook listener in integrator.io to receive incoming information from the source application and perform flows according to the message content.

Tip: Organizations may use different terms for webhook technology. Consult the API documentation for your source app to determine how it refers to these concepts.

Create a webhook listener (current UI)

These instructions apply to the universal Webhook connection. If you are listening for a webhook from a built-in integrator.io connection, instead choose that Application and then configure the export to use a webhook.

1. From the Resources menu, select Export.
2. In the resulting Create export panel, select Webhook for the Application setting.The Create Listener panel opens.
3. Enter a Name and a brief Description for the webhook.
4. Click Next.
5. In the Security section, select one of the following Verification type options:
   • Basic – The simplest verification method, relying on transport-level encryption for each request. Enter your Username and Password.
   • HMAC – A hash function and a secret key authenticate requests, configured with the following settings:
     • Algorithm: SHA-1 or SHA-256
     • Encoding: Base64 or Hexadecimal
     • Secret key: pasted here
     • Header: the HMAC
     To get a signature, encode the request body using the specified algorithm and secret.
   • Secret URL – Provide a generated token and a secret temporary URL to authenticate requests in the exposed settings.
   • Token – Authenticate token-based requests with a provided or generated token. Enter the JSON path of the field, such as myAuth.token, in the request body that will contain the token value. 
6. In the General URL & sample data section, click Generate URL.

You can optionally enter sample JSON data in the field provided.

Create a webhook listener (legacy UI)

Use the following steps to create a webhook listener:

1. Navigate to the application's login page, log in, and create your webhook with their user interface. See the application's API documentation for instructions.
2. From the Tools & Resources section of the top navigation menu, select Exports.
3. Click + New Export in the upper right corner of the page.
4. Enter a Name and a brief Description for the webhook.
5. Use the Application drop-down menu in the Were would you like to export data from? section to select Webhook.

   Note: integrator.io has webhook connectors for certain applications. In such cases, select the application itself instead of using the generic webhook item, then click the webhook radio button (instead of API) during configuration.

6. Use the Provider drop-down menu to select the source application for the webhook. If you do not see the provider in the list, select Custom.
7. The Security section dynamically changes according to the provider you select. If you are using a known provider, enter the information for the verification method required by that provider. If you are using a custom provider, select one of the following options from the Verification Type drop-down menu:
   • Basic - Basic authentication is the simplest verification method. It relies on transport level encryption with a username and password for each request. If you choose to use basic authentication, enter your Username and Password in the fields provided.
   • HMAC - HMAC authentication uses a hash function and a secret key to authenticate requests. If you choose to use HMAC authentication, complete the following fields:
     1. Select SHA-1 or SHA-256 from the Algorithm drop-down menu.
     2. Select Base64 or Hexadecimal from the Encoding drop-down menu.
     3. Enter a Secret Key in the field provided.
     4. Enter the Header (containing HMAC) in the field provided.
   • Secret URL - Secret URL authentication allows you to use a generated token and a secret temporary URL to authenticate requests. If you choose to use secret URL authentication, complete the following fields:
     1. Click Generate URL Token to create a custom URL token. Integrator.io automatically generates the URL token and the public URL that you can use to authenticate the generated token.
     2. Click Copy Token to save the Custom URL Token value to your clipboard. 
   • Token - Token-based authentication allows you to use a generated token to authenticate requests. If you choose to use token-based authentication, complete the following fields:
     1. Click Generate URL Token to create a custom URL token.
     2. Click Copy Token to save the custom URL token value to your clipboard.
     3. Enter the Path in the field provided.
8. In the Public URL & Sample Data section, click Generate URL.
9. You can optionally enter sample data in the field provided. Sample data can be in either JSON or XML format, but you can also use the XML parser in the Dev Playground to convert XML to JSON.
10. If you would like to add transform rules to the webhook export, click the pencil icon to add a rule. For more information on transforms, see Transform data.

Demonstration video

This video shows how to create a webhook listener in integrator.io to receive data being sent from source systems in real time.

Note: The user interface in the below video is outdated. The content will be updated soon.