[go: up one dir, main page]
Skip to content

Working with incoming webhooks#

Receiving incoming data in the GREEN API is implemented through incoming notifications. There are 2 ways to receive notifications HTTP API and Webhook Endpoint.

Below are recommendations for working with webhooks and notifications:

  1. Receive incoming notifications
  2. Processing incoming notifications
  3. Security when receiving notifications
  4. Logging and error handling
  5. Scaling and load balancing

1. Receiving incoming notifications#

Working with HTTP API#

When working via HTTP API methods, you need to call 2 API methods sequentially:

  1. Calling the method receiveNotification depending on the presence of messages, method settings and instance settings in the response. You will receive an object with a number and a notification object.

    If there are no notifications in the queue, the response will be null.

  2. After receiving a notification, you need to process the incoming notification with a handler and delete the notification using the deleteNotification method by passing the number of this notification.

    If the method terminated with a status code of 500 or more, the method request must be repeated.

Working with Webhook Endpoint#

During the work with Webhook Endpoint methods, you need to configure a web server that is able to accept HTTP requests.

Web server must be able:

  1. Accept incoming POST requests (webhook)

  2. Process an incoming notification.

  3. Return a response with status code 200 (after receiving status code 200 from the server, the notification will be removed from the queue).

    The waiting time for a response from your web server is 180 seconds; if the server does not return status code 200, the GREEN API server will pause for 60 seconds and resend the current notification.

2. Processing incoming notifications#

All the types and formats of notifications are specified in the documentation.

It is recommended to process incoming notifications according to the instructions below:

  1. After receiving a notification by the handler service, it is advisable to check the notification scheme (JSONSchema).

    It is not recommended to check the schema for additional fields, since the API may expand by adding new functions and information.
    If you receive a notification in which a field is missing or its format is incorrect, you need to record such a notification in the logging system and inform the operator by indicating this notification, this will help record and understand the error in the future.

  2. The handler service must find the required typeWebhook field and, depending on its type, process or reset the notification.

  3. After processing the notification, the handler must return status code 200.

    This way, all notifications that are not processed for you will be removed from the queue and subsequent notifications will arrive correctly.
    If you do not use certain types of notifications, we recommend resetting unnecessary notifications by giving status code 200, this way you will eliminate handler errors and when new functionality is released you will not have problems with the integration.

The example of a simple server from GREEN API:

3. Security when receiving notifications#

During the design of the service it is important to pay attention to security.

When working with HTTP API technology, your IP address is private and not accessible to other Internet users; this technology works well in small systems with a small amount of data.

When working with Webhook Endpoint technology, your IP address is accessible to another user, it is necessary to exclude harmful influences on your system from the outside.

Security recommendations during the usage of the Webhook Endpoint technology:

  1. Set up a firewall and allow access to the server only from the IP addresses you require.

  2. Restricting access only from certain IP addresses. You can configure your web server to accept incoming requests only from GREEN API IP addresses.

  3. Use an authorization token when sending notifications. Specify the authorization token in the webhookUrlToken field via console or using the setSettings method.
Example IP address filtering code in python 
from flask import Flask, request

from datetime import datetime
import json

app = Flask(**name**)

# List of Green Api IP addresses

ALLOWED_IPS = [
   "51.250.84.44",
   "51.250.94.65",
   "51.250.89.177",
   "64.226.125.75",
   "158.160.49.84",
   "46.101.109.139",
   "51.250.95.149",
   "51.250.12.167",
   "209.38.202.24"]

# Function to check allowed IP addresses

def check_ip():
client_ip = request.remote_addr
if client_ip not in ALLOWED_IPS:
return False
return True

@app.before_request
def before_request():
if not check_ip():
return "Access Denied", 403

# The rest of your application code...

if **name** == "**main**":
app.run()

4. Logging and error handling#

It is recommended to set up a logging system:

  1. Use a multi-level custom logging system. Log schema problems at the ERROR level, new notification types at the WARN level, unprocessed message types at the DEBUG level, and system operation at the INFO level. By turning on the required level of logging, you will be able to debug the system and identify all problems associated with integration.

  2. It is recommended to inform the operator about unknown types of notifications and notification errors; this will allow the problem to be localized as quickly as possible and will provide more information to the operator without missing notification types that are not yet supported by the integration.

Be sure to log notification data; the record must contain information including the date and time of receipt - timestamp, notification type - typeWebhook and other notification data. This will allow you to analyze the operation under unexpected scenarios of system operation.

5. Scaling and load balancing#

As you increase the size of your system, you may encounter scaling issues. It is recommended to scale the system by distributing the load across several handler microservices; for this you can use a load balancer.

As an example of a balancer, let's use the nginx web server. You can use several instances of your server and distribute the load between them using nginx.

Nginx is a high-performance web server that can also be used as a load balancer (the process of distributing web traffic evenly across multiple servers) , preventing one server from being overloaded. Nginx uses various algorithms to optimally distribute traffic and can be configured to ensure system reliability when one or more servers fail.

Use one of the following methods to deploy multiple server instances:

Manual deployment on different servers or virtual machines:#

  • Create or rent multiple physical servers, virtual machines or containers.
  • Configure each server to contain a copy of your application.

Using containerization with Docker:#

  • Create a Docker image of your application.
  • Run multiple containers with this image on one or more host machines.

Using cloud providers:#

  • Deploy multiple instances of your server on a cloud provider platform such as Amazon Web Services (AWS), Google Cloud Platform (GCP) or Microsoft Azure.
  • Use cloud infrastructure management tools to automate server deployment and scaling.
Example nginx configuration file for load balancer 
http {
   upstream app{
      server 10.2.0.100;
      server 10.2.0.101;
      server 10.2.0.102;
   }

   // This server accepts all traffic on port 80 and forwards it upstream.
   // Please note that the upstream name and proxy_pass must be the same.

   server {
      listen 80;

      server_name mydomain.com;

      location / {
         include proxy_params;

         proxy_pass http://app;


         proxy_redirect off;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
      }
   }
}