Skip to content

Etendo Webhooks

Javapackage: com.etendoerp.webhookevents

Overview

What is a Webhook?

A webhook is a method used by web applications to send real-time notifications or data to other applications or servers. Webhooks operate using HTTP callbacks, which means that an application sends an HTTP request to a specified URL (the webhook URL) when a particular event occurs.

In simple terms, a webhook acts as a messenger that delivers a message (data payload) from one application to another when certain conditions are met. Webhooks enable applications to communicate and share information automatically, making it easier to integrate different services and create seamless workflows.

By using webhooks, you can keep your applications in sync, automate processes, and extend the functionality of your applications with minimal effort.

This documentation will guide you through the process of setting up and using webhooks in Etendo Classic. Webhooks allow you to execute actions via a URL call, providing a powerful way to integrate with external services.

Webhook Description

Webhook Header Fields

Field Description
Name Webhook name
Description Webhook description
Java Class Class in which the webhook service was created
Module Module in which the webhook will be created
Active Webhook status (Active by default)

Webhook Header

Webhook Tabs Fields

Webhook window has 2 tabs: Access and Params.

The params tab allows you to create parameters that will be used in the URL call.

The access tab allows you to create access that will be used in the URL call.

Params

Field Description
Name Parameter name that will be used in the URL call
Is required Whether the parameter is required or not
Active Parameter status (Active by default)

Access

Field Description
Active Access status (Active by default)
Token Selector with the token that will be used in the URL call created on User API Token window

Webhook Usage Example

Setting up Webhooks

  1. Navigate to the new menu option: Application → General Setup → Application → Webhook Events → Webhooks
  2. Create a new webhook by filling in the required fields:

    Field Value
    Name Alert
    Description Create alert with custom message
    Java Class com.etendoerp.webhookevents.ad_alert.AdAlertWebhookService

    Webhook Alert

  3. Focus on "Params" tab and create the following params:

    Field Value Is required
    Name description ✅
    Name rule ✅

Webhook Params

API Key Generation

  1. To give execution permission to a user, go to: Application → General Setup → Application → Webhook Events → User API Token
  2. Create a new API with the Name: <<user>> token
  3. After saving, run the “Get API Key” option, and save the resulting token (64-length random string) to your clipboard.

Webhook Token

Assigning Webhook Access to Users

  1. Navigate to: Application → General Setup → Application → Webhook Events → Webhooks
  2. Select the created webhook and open the access tab.
  3. Create a new row and select the previously created API record.

Webhook Access

Executing the Webhook

To execute the webhook, make a GET request using a REST client like Postman with the following syntax:

URL=http://localhost:8080/
CONTEXT=etendo
WEBHOOK_ENDPOINT=/webhooks/
[VARS]
WEBHOOK_NAME=name=alert
APIKEY=8b1012f0d442406ed602d87c13edcee9
DESCRIPTION=new alert description
RULE=649BBFA37BA74FA59AEBE7F28524B0C8

Example URL:

http://localhost:8080/etendo/webhooks/?name=Alert&apikey=<api-key>&description=new alert description&rule=649BBFA37BA74FA59AEBE7F28524B0C8

Success

This webhook creates an alert, and you can visualize it in the "Alert Management" window.

The response will return a status code 200 and the alert ID, for example:

{
  "created": "91FEABC1604E404CB565FC79435C4344"
}

Example code usage

AdAlertWebhookService.java
/**
 * Example webhoook to take as a starting point.
 * This service receive a description and a alert rule ID and insert one standard alert
 */
public class AdAlertWebhookService extends BaseWebhookService {
  private static final Logger log = LogManager.getLogger();

  @Override
  public void get(Map<String, String> parameter, Map<String, String> responseVars) {
    Alert alert = new Alert();
    alert.setAlertRule(OBDal.getInstance().get(AlertRule.class, parameter.get("rule")));
    alert.setDescription(parameter.get("description"));
    alert.setReferenceSearchKey("");
    OBDal.getInstance().save(alert);
    OBDal.getInstance().flush();
    responseVars.put("created", alert.getId());
  }
}

Use Cases

Tokens Visibility

Note

👁 Users can visualize tokens of their current profile.

Warning

⚠ Other users cannot access another user's token. The API Token Window and webhook access tab will be empty.

Error Handling

Failure

If a user calls a webhook without a token or includes an incorrect API token, the backend will respond with a 401 response and a message.

Failure

If a user calls a webhook with an incorrect webhook name, the backend will respond with a 404 response and a message.

Failure

If a user calls a webhook without access, the backend will respond with a 401 response and a message.

Failure

If a user calls a webhook with a missing required parameter, the backend will respond with a 500 response and a message.

Failure

If a user calls a webhook without a newly required parameter (after the backend configuration is changed), the backend will respond with a 500 response and a message.

Failure

If a user calls a webhook with revoked access, the backend will respond with a 401 response and a message.