API Webhooks

Introduction

API webhooks within Canonic workflows enable you to make external HTTP requests to interact with third-party services or your own APIs. These webhooks can be configured to use various HTTP methods, allowing for a wide range of actions such as data retrieval, posting data, updating data, and more.

Configuration

An API Webhook is configured with the following parameters:

• Source: Select the HTTP method you wish to use: GET, POST, PUT, PATCH, or DELETE.
• URL: The endpoint URL to which the API request will be made.
• Headers: Set of key-value pairs for HTTP headers to be included in the request.
• Query: Key-value pairs that will be appended to the URL as query parameters.
• Body: A JSON payload for the request body, typically used with POST, PUT, and PATCH requests.

Creating an API Webhooks

1. To add an API webhook, click the + icon in your workflow and select API from the webhook options.
2. Fill out the properties panel with the Source, URL, Headers, Query, and Body as needed for your API call.

Example Configuration

Here is a sample configuration for a GET request to retrieve data:

• Source: GET
• URL: https://api.example.com/data

• Headers:

  • Content-Type: application/json
  • Authorization: Bearer YOURAPITOKEN
• Query: key: value (e.g. page: 1)
• Body: Not required for GET requests.

For a POST request to send data:

• Source: POST
• URL: https://api.example.com/data/create
• Headers: Content-Type: application/json
• Query: Optional based on API requirements
• Body: { "name": "New Item", "description": "Detailed description of the new item." }

Testing the API Webhook

Before finalizing your workflow, use the Test feature to ensure that the API webhook is configured correctly and that the response from the API is as expected.

Example

Imagine you need to integrate with an external weather service to fetch the current weather data based on the city:

• Add an API Webhook named "Fetch Weather Data".

• Configure the webhook as follows:

  • Source: GET
  • URL: https://api.weather.com/current
  • Headers: Include any required headers, such as an API key.
  • Query: Add a key-value pair for the query parameter, like city: input.cityName.

This setup sends a GET request to the weather service's API, using the city name provided in the workflow's input to fetch the current weather data.

Best Practices

• Verify endpoint URLs and ensure they are accessible.
• Use the appropriate HTTP method for the action you intend to perform.
• Keep sensitive data like API tokens secure and use environment variables when possible.