Skip to main content
The first thing you must do to use the Fintoc webhooks is to build your own webhook endpoint. Building a webhook endpoint is similar to building any endpoint for your application, but we think it’s important to have a few considerations in mind before actually writing any code. We also recommend that you read our guide about good practices for implementing webhooks.

Key considerations

For every event that happens on Fintoc, a JSON HTTP (POST) request will be sent to every registered webhook endpoint. From that request, you can parse the whole event detail using the JSON body. Your webhook endpoint, then, must be able to receive POST request, handle the event information and then respond with any HTTP response code that belongs to the family of success codes (2XX).

Saving the received event

Every event sent by Fintoc as a webhook has a unique id. It is important to at least save the id corresponding to each event in your application’s database. This way, you can ensure idempotency in the received events.

Returning 2XX quickly

To confirm that an event was successfully received, your application must respond with an 2XX HTTP status code. Any response with a status code other than that will be considered a failed attempt. If Fintoc does not receive a 2XX status code, we will attempt to notify the event again. After multiple days and failed attempts, Fintoc will stop sending the event to that webhook endpoint. It is very important that you respond with a 2XX status code as quickly as possible. Any complex logic on your application triggered by the reception of a webhook should be executed asynchronously. This way, we avoid notifying you multiple times about events that have already been received, but that failed to respond with a 2XX status code due to an HTTP timeout.

Testing the webhook

Due to notifications to the webhook endpoint occur only under specific circumstances, it is possible that some bugs of the reception of a webhook stay unnoticed until it’s too late. That’s why we always recommend that you test your endpoints when:
  • Creating a webhook endpoint
  • Registering a webhook endpoint
  • Performing any change that can affect the reception of the webhook

Sample code