> For the complete documentation index, see [llms.txt](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter.unico.io/you/Ol1H6eGO4sQvPYB1Nmyl/additional-resources/webhooks.md).

# Webhooks

## What is a Webhook?​ <a href="#o-que-e-um-webhook" id="o-que-e-um-webhook"></a>

A **webhook** is a systemic notification service that allows 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 <a href="#como-configurar-o-webhook" id="como-configurar-o-webhook"></a>

The webhook configuration is performed by the Unico team during the integration onboarding process. To do this, the team will request the following information:

* **Notification URL**: This is the endpoint used for notifications about status updates.
* **Authentication Type**: To ensure the security of the data transmitted to your endpoint, our system supports multiple authentication strategies, select the authentication method required to secure the webhook requests. The following options are available:
  * **OAuth2:** Uses a client ID and client secret to obtain an access token.
    * The following information needs to be provided:
      * Webhook `endpoint`.
      * OAuth2 provider `URL`.
      * OAuth2 provider `ClientId`.
      * OAuth2 provider `Secret`.
  * **Basic Authorization:** Requires a username and password.
    * It is necessary to send in the format `user:pass`.
  * **API Key:** Uses a unique key passed in the request header.
    * Two formats are possible:
      * `header:value`, when a specific header name is desired.
      * `value`, when the desired header is `Authorization`.
  * **No authentication:** The webhook will be sent without any credentials (not recommended for production).
* **Retry Settings**: Indicates the number of attempts in case of a failure in calling the endpoint:
  * Maximum number of attempts.
  * Interval between attempts (in seconds).
  * **Rate Limit**: Maximum number of simultaneous sends (maximum: 500).
  * **Timeout**: Maximum wait time for the endpoint's response (in seconds).
* **Status to be Notified**: Currently, the notification is sent whenever the state of a process changes to:
  * `completed`;
  * `processing`;
  * `expired`;
  * `failed`;
  * `canceled`.

### Integration with the Unico You

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

The information sent by the platform to the API includes:

* `id`: ID of the transaction.
* `status`: State of the transaction.

#### Requests​ <a href="#requisicao" id="requisicao"></a>

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 the status, as shown in the following example:

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

{% hint style="warning" %}
**About the response status:**

Currently, the platform has a set of statuses that may change in the future. Therefore, it is recommended that the statuses you are interested in for taking action be configurable.
{% endhint %}

The response should be synchronous. The status for successful requests must be in the range of 200 to 299. Any other status is considered a failure, and the platform will then retry the notifications (with exponential backoff between attempts), until receiving a 2xx response or reaching the maximum number of retries.

### Points of attention <a href="#points-of-attention" id="points-of-attention"></a>

#### **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 receiving transaction statuses within the established response time. The query to the endpoint is described in the GetProcess sections for each integration method.

#### **Rate limit**

In order to avoid overloading your resources in situations of high transaction volume, 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 low. Otherwise, the webhook throughput will be automatically reduced, and this reduction, along with the retry mechanism, may lead to an increase in the execution time of new webhooks.

#### **Idempotency**

The current webhook implementation guarantees at-least-once delivery, meaning the same status may be notified more than once. Therefore, the endpoint implementation must be idempotent.