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 retrieve the status of a process by calling an endpoint. This allows polling to receive information about the created processes. This means that the endpoint can be called multiple times for the same process to get the most recent status.

By using webhooks, it is possible to notify a specific endpoint every time the status of a process is changed.

What is a webhook?

---

A webhook is a system notification service that enables asynchronous integration between systems, where one system notifies the other through a trigger. This way, webhooks can keep systems updated with the latest information without the need for constant polling 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 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 or API Key:

  • For Basic Authentication, it must be sent in the format user:pass.

  • For API Key, it can be sent in two formats:

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

    • value, when the desired header is Authorization.

• Retry Settings: Indicates the number of retry attempts in case the endpoint call fails:

  • 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

---

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

The information sent by the platform to the API includes:

• ID: Transaction ID;

• Status: Transaction status.Integration with IDPay

Webhook configuration. After sending this information, the expected response should be synchronous.

Requests

---

The request should be a POST method in a REST API, making it easier and more secure to send the information. All fields should be mandatory. The request body should accept the transaction ID and the 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.