Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.maestra.io/llms.txt

Use this file to discover all available pages before exploring further.

A webhook is a mechanism that sends automatic notifications and data between your services when certain events occur. Using webhooks in Maestra, you can react to various events, launch relevant flows, and automate customer interactions. To send a request to a service with a webhook, you should first integrate this service and then set up necessary webhooks.

​
Creating an integration point

  1. Go to the “Integrations” section and click “Add Integration”:
00_webhook
  1. Select the “Webhook Integration” preset:
01_webhook
  1. Set up your integration.
3.1. Enter a name. 3.2. Specify general settings.
  • URL is the root URL, generated by your client, which is used by all your webhooks. You can either set the entire URL or just specify the root part and add unique URL parts for each individual webhook. ​ ​Example: Maestra’s root URL is https://api.maestra.io/v3/operations/ with various service requests. In a case like this, you can set the part common for all your webhooks using the integration and only specify a unique ID for each individual webhook. 02_webhook
  • Set the maximum number of requests per second allowed — a useful workaround for services with a limited processing speed.
All the webhooks in the integration share the same processing limit.
Please note the estimated restriction as the actual number of requests per second may vary based on the network delays. We recommend setting a slower speed than your service can process to reduce the risk of exceeding the limit. 03_webhook 3.3. Headers. Set the necessary headers for your service. “Authorization” and “Content-Type” are the most commonly used. If a header is labeled as private, the system will hide its value for users without access to integrations during the setup of your integration’s webhooks. 04_webhook 4. Click “Save”. You can now create webhooks for your integrations. 05_webhook

​
Creating a webhook

  1. Add your webhook from the integration page or go to Integrations → Webhooks:
06_webhook 07_webhook 2. Set up your webhook. 2.1. Choose the name that will be displayed for your webhook in the campaigns list and in flow steps. 2.2. Fill out the general settings.
  • System name should be unique to process your webhook response.
  • The Description is an optional field that can contain any useful info about the webhook’s function.
  • Method is determined by the task — GET, POST, PUT, PATCH, DELETE.
  • The URL is an optional part to the root URL specified in the integration and can be left blank if the full URL is already included in the integration.
  • The URL view displays the full URL request for visualization purposes only and does not require editing.
Idempotency key If you add the $\{WebhookRequest.TransactionalId\} parameter to your request, the webhook will be called back three times within six minutes if the response contains errors 5xx and 429, as long as the response does not include other codes or an absent transactionID. This parameter is optional.
08_webhook

​
How to add a transactionID

You can enter the idempotency key in a URL, a header, or a request body.
Please check the documents of your service whether it accepts the transactionId parameter and how it is best sent in webhooks, as data format requirements may vary among services.
Now, let’s have a look at the examples of how the transactionID is added to the webhook’s URL. The transactionId=${WebhookRequest.TransactionalId} is added after the question mark ?: 09_webhook Multiple parameters are separated with the ampersand &: 10_webhook 2.3. Headers.
  • The integration inherits specific headers which can be modified by deselecting the “Use” option.
  • Additional headers are those included for a specific webhook.Both inherited and additional headers are used when calling a webhook. 11_webhook Here is the final set of headers for this example:
  • Content-Type: application/json
  • webhookHeader: test 2.4. Request body. You can use Dynamic parameters in the request body, including if-else-if-end blocks, as well as for-end for cycles, passed using a JSON code. 12_webhook You can access Dynamic content message variables page located in the right sidebar. 2.5. Webhook response. If you are using a webhook response, include it in your flow. You can use both the webhook successful delivery status and specific values from the webhook response. Example of how to add a variable: 13_webhook Please refer to this article to learn more about using webhook responses.
  1. Click “Save”:
14_webhook Helpful article: