Skip to main content

Create webhook listeners

Tom Santiago
  • Updated

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

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.

Note: XML is supported for webhooks, but the sample data in the webhook allows only JSON. You can convert XML to JSON in Dev playground with the XML parser helper.

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.
2021-06-09_13-09-22.png
  1. Click Start debug and choose a period of time for the debugger to capture data.
webhook1.png
  1. Perform an action that generates the trigger to send data to the webhook listener within the external application.
  2. Select a log to review data received by the integrator.io webhook listener.
webhookRequestlogs.png

Webhook listener debug logs demonstration video

Related articles

Comments

2 comments

Date Votes
  • Shane Brown
    Engaged
    Celigo University Level 1: Skilled

    What content types will the Integrator webhook accept? Will it accept multipart/form-data?

    0
  • Stephen Brandt Documentation Manager Community moderator
    Engaged
    Great Answer
    Top Contributor
    Celigo University Level 3: Master

    Hi, Shane Brown. Thanks for the question, which isn't directly addressed in this article yet. 

    And sorry for the delay. I needed to track down the answer as well as the relative priority for adding this feature to integrator.io. 

    Webhooks that receive multipart/form-data are not yet supported in the platform, but we are looking at adding this format, hopefully within the year. 

    0

Please sign in to leave a comment.