Understanding the notification flow

This page aims to present the Notification History. This feature is available in the API of your Gerencianet account and allows you to view the POSTs that Gerencianet trigger to the notification URL defined by the integrator. This POST contains only one piece of information: a notification token.

By the end of reading this page, it is hoped that you will be able to interpret the scenarios relevant to notifications (callbacks), as in situations where a charge in your system was not downloaded, the callback was triggered to a URL that you defined previously but that is no longer valid, &c.

Further information about the notification URL definition process and the mechanics involved in querying the details of a notification can be seen on the page Receiving notifications.

Knowing more about the notification flow

The fact that the POST was sent Successful(200) to your notification URL does not in itself mean that the flow was normal. As soon as you receive the POST, you will need to come here to consult this information.

important

The POST that Gerencianet sends to your URL does not contain the charge information, but only the notification token. All information about said billing will be returned as soon as you consume the GET /notification/:token endpoint

What actually happens is a "two-way street", that is, Gerencianet triggers a POST to its notification URL with each change in the charge status, and then your system, in possession of the notification token , sends a consumption request to the GET /notification/:token endpoint, where :token is the notification token contained in the sent POST.

In this way, we can consider that:

• Subtab Notification History : indicates the POSTs that Gerencianet triggers for the registered notification URL.

• Subtab Request History : when you successfully receive the POST from Gerencianet in your URL, your system will consult the endpoint GET /notification/:token, where :token will be the notification token that we send you .

The flow is determined in the following order:

1. Gerencianet triggers the POST containing the notification token to the registered notification URL whenever there is a change in the charge status. Details can be seen in the Notification History subtab;

2. Your URL received the POST, causing your system to send a GET request to the /notification/:token route, where :token will be the notification token we sent to you. You can view this request in the Request History subtab.

important

If the integrator queries the sent token, we consider that the notification was successful. If not, we try again for up to 3 days.

That is, if there is a request to the GET /notification/:token endpoint, we understand that you received the POST with the notification token and that you consulted it, receiving as a response all informational data about the change suffered by the charge, as the previous and current billing status.

This information can be viewed in the Request History subtab, searching for the notification token in question.

To facilitate the understanding and visualization of the scenarios, let's look at some examples:

Example 1: Notification with "Success (200)"

In this animation, we demonstrate a scenario in which the integrator successfully received the POST sent by Gerencianet in its notification URL and then queried the content of this notification token in our webservice.

So that you can check it yourself, first access the Notification History subtab and, in possession of the notification token of the charge you want to verify, access the Request History subtab, search for that token and, when find it, click on the "eye" icon in the last column. In this way, you will see all the information of the referred charge that your system consulted (read).

note

In the Notification History subtab, displaying the Success (200) response only indicates that the POST was successfully sent to your notification URL, but does not guarantee that your system was able to read and record the information on your side. To do so, it is necessary to access the Request History subtab and locate the line containing the consumption of GET /notification/:token.

Summary of the steps followed:

• Gerencianet successfully sent a notification (POST) to your notification URL (via subtab Notification History);

  • This POST contains only the notification token, which is 7dd52fed-3d0a-42c8-b3fb-fc24f1d75303;

• As soon as the URL received the notification, your system sent a GET request to the route /notification/7dd52fed-3d0a-42c8-b3fb-fc24f1d75303 (see subtab Request History);

  • At this moment, your system received a JSON as a response with all the information about the change in the charge;

• For this example, the entire flow was successful: we triggered the notification containing the notification token and then your system consulted our webservice to find out (read) the information about that charge.

---

Example 2: Notification with "Failed (404)"

In this animation, we demonstrate a scenario in which Gestãonet sent a POST (notification), but in Notification History the response Failed (404) is displayed.

This Fail (404) indicates that the requested resource was not found. You must ensure that your URL is correct, as we tried to deliver the notification to the URL you provided, but the address was not found.

Therefore, as your system was not able to receive our callback, you will not see the consumption of GET /notification/:token in the Request History subtab.

Suggested Solutions:

• You can adjust the URL path on your server side;

• Update the notification URL to the new (and correct) address. For this, you can send PUT requests to the appropriate API route, taking into account the limit of up to 7,500 requests every 24 hours to this endpoint.

  • After changing the notification URL, we will continue to trigger the billing notification, but now to the new URL provided, as long as our first send was not more than 3 days ago. In this case, you can resend API callbacks following guidelines from our FAQ.

---

Example 3: Notification with "Failed (301)" or "Failed (302)"

In this animation, we demonstrate a scenario in which Gestãonet sent a POST (notification), but in Notification History the response Failed (301) or Failed (302) is displayed .

These situations occur when there is a permanent or temporary redirect (301 or 302, respectively) on your server, specifically affecting the notification delivery to the notification URL you previously defined. Some common examples of when this occurs:

• You set your notification URL to http://www.mysite.com.br, but later installed HTTPS/SSL on your server and your address was https://www.mysite.com.br ;

• Your notification URL was https://www.mysite.com.br, but later you created rules on your server (via htaccess, web.config, etc) and the address started responding only as https ://mysite.com.br.

Suggested Solutions:

• Better adjust the 301 and/or 302 redirect rule on your server;

• Update the notification URL to the new (and correct) address. For that, you can send PUT requests to the appropriate API route, taking into account the limit of up to 7,500 requests every 24 hours for this endpoint.

  • After changing the notification URL, we will continue to trigger the billing notification, but now to the new URL provided, as long as our first send was not more than 3 days ago. In this case, you can resend API callbacks following guidelines from our FAQ.

---

Example 4: Notification with "Failed (500)"

In this animation, we demonstrate a scenario in which Gestãonet sent a POST (notification), but in Notification History the response Failed (500) is displayed.

Responses containing Failed (500) or 500 Internal Server Error are an HTTP error status that indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

The error, however, is a generic, all-encompassing message which indicates a difficulty in processing on your server and can occur due to several factors.

Therefore, your server's log files may sometimes respond with a code 500 status accompanied by more details about the request to prevent errors of this type from happening again in the future. Therefore, it is always extremely important that you see the error message in your server log to help you resolve it.

The following is a list of possible causes that you can explore to troubleshoot the error:

• Configuration file on your server, such as .htaccess, php.ini or web.config with invalid parameters.

• Blocking on your server (network, firewall, policies, etc): some applications and services may have certain filters, so make sure that our IP addresses are released.

• High resource consumption on your server or process limit: shared hosts are more susceptible to this type of situation.

• Timeout on your server.

• Incorrect server permissions on files and/or folders.

• Memory limit and PHP directives set in the php.ini file.

• Conflict between PHP versions on your host.

• Possibility of plugins, modules, extensions or themes causing the error due to incompatibility or automatic updates.

note

As this is a generic error, it is important that you consult and interpret your server's error logs:

• Apache: /var/log/apache2/error.log
• NGINX: /var/log/nginx/error.log

If you do not have access to such information, please contact your hosting provider or its technical team responsible for the network infrastructure.

---

HTTP status codes (2xx, 3xx, 4xx and 5xx)

Gerencianet uses HTTP responses to indicate success or failure in requests. You can usually view them via the Notification History subtab.

Commonly, when we return responses with status 2xx it means that the request was successful; 3xx status indicates redirection; status 4xx indicates failures in sending data from the client; status 5xx indicates internal server errors.

The following table presents the HTTP codes of the most common responses, as well as their explanations and solutions:

Code	Name	Description
200	OK	Request was successful.
301	Moved Permanently	Permanently redirect a page to another address. You must update to the correct URL to receive the notification token. URL tuning can be performed on your server side or by sending PUT requests to the proper route (learn how).
302	Found	Redirection of a page to another address, but with indication of a temporary character, not permanent. You must update to the correct URL to receive the notification token. The adjustment of the URL can be performed on the side of your server or sending PUT requests to the proper route (learn how).
400	Bad Request	Some mandatory parameter was not sent or was sent in an invalid way. Consult the "request history" to interpret the API returns (learn how) and correct the syntax and/or parameters of the request you are sending to the Gestoret API.
401	Not Found	The requested resource was not found. That is, the 404 return appears when the resource (URL/document/file) requested from a destination server does not exist or is not found. Make sure your URL is correct for receiving the notification token. URL tuning can be performed on your server side or by sending PUT requests to the proper route (learn how).
404	Not Found	The requested resource was not found. That is, the 404 return appears when the resource (URL/document/file) requested from a destination server does not exist or is not found. Make sure your URL is correct for receiving the notification token. URL tuning can be performed on your server side or by sending PUT requests to the proper route (learn how).
500	Internal Server Error	Internal server error. The server encountered an unexpected condition that prevented the request from being fulfilled. It usually indicates an error coming from the web server. A common cause is an error in the .htaccess. To find out, read your server's error log. It is worth remembering that this type of error is not accessible by PHP, so you will not be able to read the details of the log by activating the display of errors in PHP. However, the error is not always the webserver, as it is possible to configure the environment so that errors from PHP or another module, for example, are treated by the webserver with status 500.

note

If you are encountering any response code other than those mentioned above, we recommend that you access the HTTP status code list from Wikipedia and check.