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
• Webhook listener debug logs

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 initiate the flow with the data sent.

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

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: This is the secret key provided to you for the webhook. This is required to generate the hash value.
     • Header: This is the header name in your HTTP request. For example, the header name for Slack webhooks is "X-Slack-Signature".
     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 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.

0:15 Create a webhook in integrator.io
0:30 List of webhook providers
1:00 Custom webhooks
2:40 Generating a webhook URL

Webhook listener debug logs

integrator.io allows you to capture requests received by a webhook listener within a specified time period. You can then view the logs to verify that the data includes all expected information.

Use the following steps to review data sent from a webhook:

1. Open the flow that contains a listener export step.
2. Click Listener to open the Edit listener panel.
3. Click View debug logs in the upper right corner of the Edit listener panel.

4. Click Start debug and choose a period of time for the debugger to capture data.

5. Perform an action that generates the trigger to send data to the webhook listener within the external application.
6. Select a log to review data received by the integrator.io webhook listener.

Webhook listener debug logs demonstration video