Webhook

In this section, you will find information about how the Webhook works for the Unico IDPay product.

---

The GetProcess articles in this documentation describe a way to obtain the status of a process through a call to an endpoint. In this way, polling is performed to receive information about the processes that have been created. This means that the endpoint can be called multiple times for the same process to get the most recent 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?

---

A webhook is a systemic notification service that enables asynchronous integration between systems, where one system notifies the other via a trigger. This way, webhooks can keep systems updated with the most recent information without the need for constant polling to check for updates.

How to configure the Webhook

---

To configure the webhook, the following information is required:

• Notification URL: This is the endpoint used by By Unico for notifications about status updates.

• Authentication Type: This is the method used to authenticate the invocation of the endpoint. The following options are available:

  • OAuth2;

  • Basic Authorization;

  • API Key;

  • No authentication.

• For OAuth2, the following information needs to be provided:

  • Webhook endpoint ;

  • OAuth2 provider URL ;

  • OAuth2 provider ClientId ;

  • OAuth2 provider Secret .

• For Basic Authorization, it is necessary to send in the format user:pass.

• For API Key, two formats are possible:

  • header:value, when a specific header name is desired;

  • value, when the desired header is Authorization.

• Retry Settings: This indicates the number of attempts in case of failure when calling the endpoint:

  • Maximum number of attempts;

  • Interval between attempts (in seconds);

  • Rate Limit: Maximum number of simultaneous submissions (max: 500);

  • Timeout: Maximum waiting time for the endpoint response (in seconds).

• Status to be notified: You can subscribe to specific statuses to receive notifications. These include:

  • approved: Transaction approved;

  • processing: Transaction in processing;

  • inconclusive: We couldn't perform a conclusive validation;

  • shared: Transaction shared, waiting for submission;

  • skipped: The person skipped the biometric capture in the flow;

  • unknown-share: The person marked that they don’t recognize the purchase;

  • absent-holder: The cardholder is not present to perform the capture;

  • expired: The person didn’t complete the capture within the established time and the transaction was expired.

About 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.

Integration with IDPay

---

When configuring a webhook on the platform, you can receive information about the processes through notifications sent to an endpoint of the API you developed to receive these updates.

The information sent by the platform to the API includes:

• ID: Transaction ID;

• Status: Transaction status.Integration with IDPay

Note that it is possible to choose the statuses the client wants to be notified about through the webhook configuration. After sending this information, the expected response should be synchronous.

Requests

---

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

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

Response

---

The response should be synchronous. The status for successful requests should be in the range of 200 to 299. Any other status will be considered a failure, and IDPay will make additional notification attempts (with exponential backoff between them), until receiving a 2xx response or reaching the maximum number of attempts.

Response Status

---

Currently, we have a set of statuses, but this set may change in the future. Therefore, it is recommended to make configurable the statuses that the client is interested in to take action. For example, if the intention is to take action every time a capture is successfully completed, this currently happens with the status "processing." However, since this could be modified in the future, it is recommended that the status indicating successful capture be configurable in the system, so a future change to the "captured" status can be easily implemented.

Additionally, we recommend having specific actions for specific statuses and a general action in case the status is unrecognized (for example, assuming that anything different from "processing" and "approved" is inconclusive). This is important because new statuses may appear in the future, and it is not expected for the webhook to break due to this.

Important Considerations

---

Pay attention to the following aspects when developing the API that IDPay will use to notify status changes:

Rate limit

In order to avoid overloading your resources in situations with many transactions, it is possible to specify an upper limit on the number of times the endpoint can be invoked.

Error Rate

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

Idempotence

The current webhook implementation guarantees at-least-once delivery, so the same status may be notified more than once. Therefore, the endpoint implementation should be done in an idempotent manner.

Fallback

In case of any unavailability in the webhook service, it is recommended to have a fallback method in place so that you can continue retrieving the transaction statuses within the established response time. The endpoint query is described in the "API Reference" section of this documentation.

---

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.