Outgoing webhooks

Outgoing webhooks


While a webhook trigger allows you to start a flow based on data updates received from an application, Outgoing Webhooks enable you to send HTTP requests to external applications or services.
Outgoing webhooks allow you to access any API through http requests using a custom connection. These connections automatically handle the refresh logic, making it easier to integrate with applications. You can use these connections just like any built-in connection, allowing you to integrate applications using both outgoing webhooks and custom functions.
You can use the outgoing webhooks for the following scenarios:
  1. Integrate external applications or missing actions: If your workflow depends on an application or specific actions that aren't currently available in Zoho Flow, you can use outgoing webhook to access the application's API, create a custom connection, and seamlessly integrate them into your flow.
  2. On-prem app integration: For businesses that require integration with on-prem apps, outgoing webhooks offer support to integrate them.
  3. Real-time data updates: It also supports real-time updates, enabling your application to send data instantly to a designated URL whenever a specific trigger or event occurs.

Some important terms

Headers

Additional information transferred along with the http request for purposes, such as authorization and identification.

Access token
A credential used to access a resource (API) for the first time. A new access token must be generated each time the previously granted access token expires. 

Refresh token
A refresh token is a special token that is used to obtain new access tokens when the existing one expires.

Refresh logic
The process of using a refresh token to obtain a new access token when the current one expires. This process is crucial for maintaining secure access to resources (APIs) and eliminates the need for the user to re -authenticate manually.

Auth Profiles
Auth profiles help you connect to external applications or services by storing the authentication details. It helps you create connections for outgoing webhooks.

API Methods 

GET - Fetch data from a server (Read).

PUT - Replace existing data on a server (Update).

POST - Send new data to a server (Create).

PATCH - Partially update existing data (Modify).

DELETE - To remove data from a server (Delete).

How to use the send webhook action in your flow 

You can use outgoing webhooks to access any API by configuring the Send Webhook action in your flow. It involves two steps: creating an auth profile and creating a custom connection. However, for applications that don't require authentication or send authentication details via headers, they can be configured using the simpler option of NoAuth.

 

For applications that require authentication, outgoing webhooks offer four authentication methods:
  1. Basic Auth: This method uses only a username and password, encoded in Base64, to access an application.
  2. OAuth v1.0a: This method uses token-based access to authorize third-party applications without exposing user credentials.
  3. OAuth v2: This method allows secure, token-based access to applications without sharing user credentials, using access and refresh tokens.
  4. API Key: This method uses a unique key, provided by the application, to verify and authorize access to the application.

Step 1: Create an auth profile 

Auth Profiles help you connect to external applications by storing the authentication details. To use the Send Webhook action in your flow, you'll need to create an auth profile for your external application. Creating an auth profile is a one-time activity where you can reuse the same profile across connections to send webhooks to your applications.

Note: 

  • If you want to delete an auth profile, you first need to delete the connections using it.

  • You cannot update the authentication method or On-Prem agent in an auth profile, because there might be connections using it.


Step 2: Create a custom connection 

Once you've created an auth profile, you can reuse the same in multiple connections to send webhooks to your applications. Each connection uses the authentication details stored in the respective auth profiles.

Note:
  1. Once you create a custom connection with an application, all connections will be listed under Settings > Connections with a Auth Profile label.



  2. You can rename your connection at any time by clicking the edit icon. To test the connection, click the Test button. If needed, use the trash icon to delete the connection.
  3. Deleting a connection removes it permanently. If you delete a connection, flows using it will fail. Actions previously executed by the flow with the connection won't be affected.
  4. If you test a connection from the Connections page without configuring the test URL while creating the custom app, you may encounter an error message.

Basic Auth
OAuth v1.0a
OAuth v2
API Key
Basic Auth
Here's a step-by-step guide to create an auth profile:
  1. Navigate to Settings > Auth Profiles and click Create.
  2. Select the Basic Auth authentication method.
  3. Enter the Auth Profile Name.



  4. Check the This app is installed on-premises checkbox if you need to connect to an application that is installed on-premises.
    Learn how to set up and manage your On-Prem agent
  5. Check the Enable test URL checkbox if you need to make a test API call and verify if the connection works as expected. Configure the test URL by entering a URL and optionally passing values for Params and Headers.
  6. Click Save.

Here's a step-by-step guide to create a custom connection:
  1. Navigate to Settings > Connections and click Create Connection.



  2. In the configuration window that appears, choose an app to create a connection, select it under Auth Profiles, and click Next.
  3. Enter the Connection Name, User Name, and Password.
  4. Click Authorize.




OAuth v1.0a
Here's a step-by-step guide to create an auth profile:
  1. Navigate to Settings > Auth Profiles and click Create.
  2. Select the OAuth v1.0a authentication method.
  3. Enter the Auth Profile Name, Request Token URL, Authorization URL, and Access Token URL.
  4. Check the This app is installed on-premises checkbox if you need to connect to an application that is installed on-premises.
  5. Check the Encode OAuth Signature checkbox if you need to encode the OAuth signature as specified in your application's API documentation.
  6. Check the Enable test URL checkbox if you need to make a test API call and verify if the connection works as expected. Configure the test URL by entering a URL and optionally passing values for Params and Headers.
  7. Click Save. 

Here's a step-by-step guide to create a custom connection:
  1. Navigate to Settings > Connections and click Create Connection.
  2. In the configuration window that appears, choose an app to create a connection, select it under Auth Profiles, and click Next.
  3. Enter a Connection Name to create a connection.
  4. For some apps, you can choose whether the connection applies to all permissions (Read, Write, etc.) or only selected ones.
  5. Click Authorize.
OAuth v2
Here's a step-by-step guide to create an auth profile:
  1. Navigate to Settings > Auth Profiles and click Create.
  2. Select the OAuth v2 authentication method.
  3. Enter the Auth Profile Name and Authorization URL.
  4. Check the This app is installed on-premises checkbox if you need to connect to an application that is installed on-premises.
  5. Check the Enable test URL checkbox if you need to make a test API call and verify if the connection works as expected. Configure the test URL by entering a URL and optionally passing values for Params and Headers.
  6. Click Save.

Here's a step-by-step guide to create a custom connection:
  1. Navigate to Settings > Connections and click Create Connection.
  2. In the configuration window that appears, choose an app to create a connection, select it under Auth Profiles, and click Next.
  3. Enter a Connection Name to create a connection.
  4. For some apps, you can choose whether the connection applies to all permissions (Read, Write, etc.) or only selected ones.
  5. Click Authorize.
API Key
Here's a step-by-step guide to create an auth profile:
  1. Navigate to Settings > Auth Profiles and click Create.
  2. Select the API Key authentication method.
  3. Enter the Auth Profile Name, Field Label, and Parameter Name, then choose the API Key Placement and Field Type.



  4. Check the Enable test URL checkbox if you need to make a test API call and verify if the connection works as expected. Configure the test URL by entering a URL and optionally passing values for Params and Headers.
  5. Click Save.

Here's a step-by-step guide to create a custom connection:
  1. Navigate to Settings > Connections and click Create Connection.
  2. In the configuration window that appears, choose an app to create a connection, select it under Auth Profiles, and click Next.



  3. Enter a Connection Name and the Field Label value.
  4. Click Authorize.


 
Configure a send webhook action in your flow

Basic Auth/OAuth v1.0a/OAuth v2/API Key:
  1. In the Builder, navigate to Logic > Webhooks.
  2. Drag and drop the Send Webhook action just like other triggers and actions.
  3. In the configuration window that appears, choose Use a connection.
  4. If a connection to the app already exists, select it from the dropdown. Otherwise, click New to create a new connection.
  5. Select a request method(GET/PUT/POST/PATCH/DELETE) from the Request dropdown and enter the HTTP URL. You can refer to your app's API documentation to get the HTTP URL.



    If the app's API supports authorization via headers or body, or query params, then enter the Param Name and Param Value (where Param Value can be the integration key/API key obtained from the application) and other header and body parameters in the respective fields.
  6. Choose a Content-Type that specifies the data format sent in the request body from the dropdown. This is typically JSON.
  7. Choose the Response Type from the dropdown menu. If the response type is either XML or Auto, then check the Convert XML to JSON checkbox if you want to convert the XML response into JSON in the action.
    Check the Show header data checkbox to fetch the header information from the response and display them as variables for mapping.
  8. After filling in all the required fields, click Save, then Test to verify if it works as expected.

Note: 
  1. Follow the same steps to configure NoAuth; in the configuration window, choose No Authentication (Point 3).



  2. Check the This app is installed on-premises checkbox if you need to connect to an application that is installed on-premises.
  3. Choose an On-Prem Agent from the dropdown menu or click New to create one.

Tips: 
  1. Individual keys in the JSON response will be available for mapping only after you test the configuration at least once.



  2. Avoid using spaces when entering the HTTP URL in the configuration window to avoid errors.