Skip to main content

Get transaction result via webhook

The article Get Process describes how to obtain transaction status by calling an endpoint. In this way, polling is carried out to receive information about the processes created. This means that the endpoint can be called several times for the same process to obtain the latest status.

With the use of webhooks it is possible to notify a specific endpoint every time the status of a process changes.

What is a webhook?​

Webhook is a systemic notification service that allows asynchronous integration between systems, where one system notifies the other through a trigger. In this way, webhooks can keep systems up to date with the latest information without the need to constantly check for updates through polling.

How to configure the Webhook​

To configure the webhook, the following information is required:

  • Notification URL: This is the endpoint used by IDUnico for notifications about status updates.
  • Authentication type**: This is the authentication method used to invoke the endpoint. The following options are available:
    • Basic Authorization;
    • API Key*;
    • No authentication.
  • Secret: Indicates a secret used for authentication. The secret is only required when the authentication type is Basic Authorization and API Key:
    • For Basic Authentication it must be sent in the format user:pass.
    • For API Key, you can send it in two formats:
      • header:value, when you want the header to have a specific name;
      • value: when the desired header is Authorization
  • Retry settings**: Indicates the number of retries in case the call to the endpoint fails:
    • Maximum number of retries;
    • Interval between retries (in seconds);
    • Rate limit: Maximum number of simultaneous sends (maximum: 500);
    • Timeout: Maximum waiting time for the endpoint to respond (in seconds);
  • Status to be notified: Currently the notification is sent whenever the status of a process changes to:
    • 2: Divergence;
    • 3: Finished;
    • 4: Cancelled;
    • 5: Error.

Integration with IDUnico​

By configuring a webhook, you can obtain information about the processes through notifications sent to an API endpoint you developed to receive these updates.

The information sent to the API is:

  • id: transaction ID;
  • status: status of the transaction;

Authentication​

The API can be protected by an authentication method such as Basic Authentication or API Key. A list of valid IPs for access can also be defined for additional protection.

Request​

The request must be a POST method in a REST API, making it easier and more secure to send the information. All fields must be mandatory. The body of the request must accept the transaction ID and status, as shown in the following example:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "3"
}

Response​

The response must come synchronously. The status for successful requests must be in the range 200 to 299. Any other status is considered a failure and then new notification attempts (with exponential backoff in between) are made until a 2xx response is received or the maximum number of attempts is reached.

Response Status​

The status of the transaction may vary in the future. It is therefore recommended that the status you are interested in taking action on is configurable.

Rate Limit​

In order not to overload your resources in situations with many transactions, you can specify an upper limit on the number of times the endpoint can be invoked.

Error rate​

The error rate (responses outside the range of [200, 299]) should always be low. Otherwise, the webhook throughput will be automatically reduced, and this reduction together with the retry mechanism may result in an increase in the execution time of new webhooks.

Idempotency​

The current webhook implementation has an at-least once delivery guarantee, so the same status can be notified more than once. Therefore, the implementation of the endpoint must be done in an idempotent manner.

Fallback​

In the event of any unavailability in the webhook service, it is recommended that there is a fallback method so that you can continue to obtain transaction statuses within the established response time. A time of 10 seconds is indicated in the fallback configuration. The endpoint query described in the article Get Process can be used for this purpose.

Any concerns?​

Missing something or still need help? If you are already a customer or partner, you can contact us through the Help Center.