Merge pull request #2270 from mercadopago/fix/webhooks-rollback

Fix/webhooks-rollback

guides/additional-content/your-integrations/notifications.en.md

@@ -18,5 +18,5 @@ There are **two types** of notifications available for configuration which ,once
 
 | Type | Description |
 | --- | --- |
-| **Webhooks** | It uses HTTP REST and instantly notifies updates. [Click here](/developers/pt/guides/additional-content/your-integrations/webhooks) to learn how to configure and simulate the sending of Webhooks notifications. |
+| **Webhooks** | It uses HTTP REST, instantly notifies updates and enhances security in your integration through the **secret signature**, a validation method to ensure that received notifications were sent by Mercado Pago. </br [Click here](/developers/pt/guides/additional-content/your-integrations/webhooks) to learn how to configure and simulate the sending of Webhooks notifications. |
 | **IPN** | The notification may take a few moments to send. To learn how to configure IPN notifications [click here](/developers/pt/guides/additional-content/your-integrations/ipn). |

guides/additional-content/your-integrations/notifications.es.md

@@ -18,5 +18,5 @@ Hay **dos tipos** de notificaciones disponibles para la configuración, que una
 
 | Tipo | Descripción |
 | --- | --- |
-| **Webhooks** | Utiliza HTTP REST e notifica instantáneamente las actualizaciones. [Haz clic aquí](/developers/es/guides/additional-content/your-integrations/webhooks) para aprender cómo configurar y simular el envío de notificaciones Webhooks. |
+| **Webhooks** | Utiliza HTTP REST, notifica instantáneamente las actualizaciones y mejora la seguridad en tu integración mediante la **clave secreta**, un método de validación para garantizar que las notificaciones recibidas fueron enviadas por Mercado Pago. </br> [Haz clic aquí](/developers/es/guides/additional-content/your-integrations/webhooks) para aprender cómo configurar y simular el envío de notificaciones Webhooks. |
 | **IPN** | La notificación puede tardar unos minutos en enviarse. Para aprender a configurar las notificaciones IPN [haz clic aquí](/developers/es/guides/additional-content/your-integrations/ipn). |

guides/additional-content/your-integrations/notifications.pt.md

@@ -17,5 +17,5 @@ Existe **dois tipos** de notificações disponíveis para configuração, que um
 
 | Tipo | Descrição |
 | --- | --- |
-| **Webhooks** | Utiliza HTTP REST e notifica instantâneamente as atualizações. [Clique aqui](/developers/pt/guides/additional-content/your-integrations/webhooks) para saber como configurar e simular o envio de notificações Webhooks. |
+| **Webhooks** | Utiliza HTTP REST, notifica instantaneamente as atualizações e traz mais segurança em sua integração por meio da **assinatura secreta**, um método de validação para garantir que notificações recebidas foram enviadas pelo Mercado Pago. </br> [Clique aqui](/developers/pt/guides/additional-content/your-integrations/webhooks) para saber como configurar e simular o envio de notificações Webhooks. |
 | **IPN** | A notificação pode demorar alguns instantes para ser enviada. Para saber como configurar notificações IPN [clique aqui](/developers/pt/guides/additional-content/your-integrations/ipn). |

guides/additional-content/your-integrations/webhooks.en.md

@@ -4,15 +4,13 @@
 
 Webhook notifications can be configured for one or more applications created in your [Developer Dashboard](/developers/panel/app).
 
-Uma vez configurado, o Webhook será enviado sempre que ocorrer um ou mais eventos cadastrados, evitando que haja um trabalho de pesquisa a cada minuto em busca de uma resposta e, por consequência, que ocorra uma sobrecarga do sistema e a perda de dados sempre que houver alguma situação. Após receber uma notificação na sua plataforma, o Mercado Pago aguardará uma resposta para validar se você a recebeu corretamente.
-
 Once configured, the Webhook will be sent whenever one or more registered events occur, avoiding a search job every minute in search of an answer and, consequently, a system overload and data loss whenever there is some situation. After receiving a notification on your platform, Mercado Pago will wait for a response to validate that you received it correctly
 
 In this documentation, we will explain the necessary settings to receive messages (through the Dashboard or when creating payments), in addition to showing the necessary actions that you must take for Mercado Pago to validate that the notifications were properly received.
 
 ## Configuration via Dashboard
 
-Below, we will explain how to specify the URLs that will be notified, configure the events from which notifications will be received and simulate the receipt of various types of notifications.
+Below, we will explain how to: specify the URLs that will be notified, configure the events from which notifications will be received, validate that the notifications you receive are sent by Mercado Pago and simulate the receipt of various types of notifications.
 
 ![webhooks](/images/dashboard/webhooks-es.png)
 
@@ -39,6 +37,63 @@ Below, we will explain how to specify the URLs that will be notified, configure
 | `delivery_cancellation` | `case_created`| Shipment cancellation request |
 | `topic_claims_integration_wh` | `updated`| Claims made by sales |
 
+5. Finally, click **Save** to generate a secret signature for the application. The signature is a validation method to ensure that received notifications were sent by Mercado Pago.
+
+> WARNING
+>
+> Important
+> 
+> Mercado Pago will always send this signature in Webhook notifications. Always verify this authenticity information to prevent fraud. </br></br>
+> </br></br>
+> The generated signature has no expiration date, and while not mandatory, we recommend periodically renewing the **secret signature**. To do this, simply click the reset button next to the signature.
+
+### Validate notification origin
+
+At the moment the registered URL receives a notification, you can validate whether the content sent in the `x-signature` header (example: `ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`) was sent by Mercado Pago, in order to enhance the security of receiving your notifications. See below how to configure this validation.
+
+1. Extract the timestamp (`ts`) and the signature from the `x-signature` header. To do this, split the content of the header by the `,` character, resulting in a list of elements.
+2. Then, split each element of the list by the equal sign `=`, resulting in a pair of prefixes and values. The value for the prefix `ts` is the timestamp of the notification, and `v1` is the encrypted signature.
+3. Using the template below, replace the parameters with the data received in your notification.
+
+```template
+post;[urlpath];data.id=[data.id_url];type=[topic_url];user-agent:mercadopago webhook v1.0;[timestamp];action:[json_action];api_version:[json_apiversion];date_created:[json_datecreated_RFC3339];id:[id_json];live_mode:[livemode_json];type:[type_json];user_id:[userid_json];
+```
+
+In the template, values enclosed in `[]` should be replaced with the notification data, such as:
+
+- Parameters with the `_url` suffix come from query params. For example, `[topic_url]` will be replaced by the value `payment` (without brackets).
+- Parameters with the `_json` suffix come from the `body` of the request.
+- `[urlpath]` will be only the domain + the path of the URL (without "http://" or "https://").
+- `[timestamp]` will be the value of ts extracted from the x-signature header.
+
+> If any of the values presented in the template below are not present in your notification, you should remove them from the template.
+
+4. In the Developer [Dashboard](/developers/panel/app), select the integrated application, navigate to the Webhooks section, and reveal the generated secret signature.
+5. Generate the counter key for validation. To do this, calculate an [HMAC](https://en.wikipedia.org/wiki/HMAC) with the `SHA256 hash` function in hexadecimal, using the **secret signature** as the key and the populated template with the values as the message. For example:
+
+[[[
+```php
+$cyphedSignature = hash_hmac('sha256', $data, $key);
+```
+```node
+const crypto = require('crypto');
+const cyphedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signatureTemplateParsed)
+    .digest('hex'); 
+```
+```java
+String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);
+```
+```python
+import hashlib, hmac, binascii
+
+cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))
+```
+]]]
+
+6. Finally, compare the generated key with the key extracted from the header, ensuring they have an exact match. Additionally, you can use the timestamp extracted from the header for comparison with a timestamp generated at the time of receiving the notification to establish a tolerance for message reception delays.
+
 ### Simulate notification receipt
 
 1. After configuring the URLs and Events, click **Simulate** to experiment and test if the indicated URL is receiving notifications correctly.

guides/additional-content/your-integrations/webhooks.es.md

@@ -10,7 +10,7 @@ En esta documentación, explicaremos las configuraciones necesarias para recibir
 
 ## Configuración a través del Panel del desarrollador
 
-A continuación explicaremos cómo indicar las URL que serán notificadas, configurar los eventos de los cuales se recibirá la notificación y simular la recepción de diversos tipos de notificaciones.
+A continuación explicaremos cómo: indicar las URL que serán notificadas, configurar los eventos de los cuales se recibirá la notificación, validar que las notificaciones que recibes son enviadas por Mercado Pago y simular la recepción de diversos tipos de notificaciones.
 
 ![webhooks](/images/dashboard/webhooks-es.png)
 
@@ -37,7 +37,62 @@ A continuación explicaremos cómo indicar las URL que serán notificadas, confi
 | `delivery_cancellation` | `case_created`| Solicitud de cancelación de envío |
 | `topic_claims_integration_wh` | `updated`| Reclamos hechos por las ventas |
 
-5. Por último y haz clic en **Guardar**.
+5. Por último, haz clic en **Guardar** para generar una clave secreta para la aplicación. La clave es un método de validación para asegurar que las notificaciones recibidas fueron enviadas por Mercado Pago.
+
+> WARNING
+> 
+> Importante
+> 
+> Mercado Pago siempre enviará esta clave en las notificaciones Webhooks. Siempre verifica esta información de autenticidad para evitar fraudes. </br></br>
+> </br></br>
+> La clave generada no tiene fecha de caducidad y, aunque no es obligatorio, recomendamos renovar periódicamente la **clave secreta**. Para hacerlo, simplemente haz clic en el botón de restablecimiento junto a la clave.
+
+### Validar origen de la notificación
+
+En el momento en que la URL registrada reciba una notificación, podrás validar si el contenido enviado en el _header_ `x-signature` (ejemplo: `ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`) fue enviado por Mercado Pago, con el fin de obtener mayor seguridad en la recepción de tus notificaciones. A continuación, te indicamos cómo configurar esta validación.
+
+1. Extrae el _timestamp_ (`ts`) y la clave del _header_ `x-signature`. Para hacer esto, divide el contenido del _header_ por el carácter `,`, lo que resultará en una lista de elementos.
+2. Luego, divide cada elemento de la lista por el carácter `=`, lo que resultará en un par de prefijos y los valores. El valor para el prefijo `ts` es el _timestamp_ de la notificación y `v1` es la clave encriptada.
+3. Utilizando el _template_ a continuación, sustituye los parámetros con los datos recibidos en tu notificación.
+
+```template
+post;[urlpath];data.id=[data.id_url];type=[topic_url];user-agent:mercadopago webhook v1.0;[timestamp];action:[json_action];api_version:[json_apiversion];date_created:[json_datecreated_RFC3339];id:[id_json];live_mode:[livemode_json];type:[type_json];user_id:[userid_json];
+```
+
+En el _template_, los valores entre `[]` deben ser reemplazados por los valores de la notificación, como:
+
+- Los parámetros con el sufijo `_url` provienen de _query params_. Ejemplo: `[topic_url]` se sustituirá por el valor `payment`` (sin corchetes).
+- Los parámetros con el sufijo `_json` provienen del _body_ de la solicitud.
+- `[urlpath]` será solo el dominio + el _path_ de la URL (sin "http://" o "https://").
+- `[timestamp]` será el valor ts extraído del _header_ `x-signature`.
+
+> Si alguno de los valores presentados en el _header_ a continuación no está presente en tu notificación, deberás eliminarlos de la plantilla.
+
+4. En el [Panel del desarrollador](/developers/panel/app), selecciona la aplicación integrada, ve a la sección de Webhooks y revela la clave secreta generada.
+5. Genera la contraclave para la validación. Para hacer esto, calcula un [HMAC](https://es.wikipedia.org/wiki/HMAC) con la función de `hash SHA256` en base hexadecimal, utilizando la **clave secreta** como clave y el _template_ poblada con los valores como mensaje. Ejemplo:
+
+[[[
+```php
+$cyphedSignature = hash_hmac('sha256', $data, $key);
+```
+```node
+const crypto = require('crypto');
+const cyphedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signatureTemplateParsed)
+    .digest('hex'); 
+```
+```java
+String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);
+```
+```python
+import hashlib, hmac, binascii
+
+cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))
+```
+]]]
+
+6. Finalmente, compara la clave generada con la clave extraída del _header_, asegurándote de que tengan una correspondencia exacta. Además, puedes usar el _timestamp_ extraído del _header_ para compararlo con un timestamp generado en el momento de la recepción de la notificación, con el fin de establecer una tolerancia de demora en la recepción del mensaje.
 
 ### Simular la recepción de la notificación
 
@@ -377,7 +432,6 @@ En la notificación recibirás un `JSON` con la siguiente información que conti
  "merchant_order": 4945357007,
  "payment_id": 23064274473
 
-
 ```
 
 > NOTE

guides/additional-content/your-integrations/webhooks.pt.md

@@ -10,7 +10,7 @@ Nesta documentação, explicaremos as configurações necessárias para o recebi
 
 ## Configuração através do Painel do desenvolvedor
 
-Abaixo explicaremos como indicar as URLs que serão notificadas, configurar os eventos dos quais se receberá a notificação e simular o recebimento de diversos tipos de notificações.
+Abaixo explicaremos como: indicar as URLs que serão notificadas, configurar os eventos dos quais se receberá a notificação, simular o recebimento de diversos tipos de notificações e validar que as notificações que recebe são enviadas pelo Mercado Pago.
 
 ![webhooks](/images/dashboard/webhooks-pt.png)
 
@@ -37,7 +37,62 @@ Abaixo explicaremos como indicar as URLs que serão notificadas, configurar os e
 | `delivery_cancellation` | `case_created`| Solicitação de cancelamento do envio |
 | `topic_claims_integration_wh` | `updated`| Reclamações feitas pelas vendas |
 
-5. Por fim, clique em **Salvar**.
+5. Por fim, clique em **Salvar** para gerar uma **assinatura secreta** para a aplicação. A assinatura é um método de validação para garantir que notificações recebidas foram enviadas pelo Mercado Pago. 
+
+> WARNING
+>
+> Importante
+>
+> O Mercado Pago sempre enviará essa assinatura nas notificações Webhooks. Sempre confira essa informação de autenticidade para evitar fraudes. </br></br>
+> </br></br>
+> A assinatura gerada não tem prazo de validade e, embora não seja obrigatório, recomendamos renovar periodicamente a **assinatura secreta**. Para isso, basta clicar no botão de redefinição ao lado da assinatura.
+
+### Validar origem da notificação
+
+No momento em que a URL cadastrada receber uma notificação, você poderá validar se o conteúdo enviado no _header_ `x-signature` (exemplo: `ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`) foi enviado pelo Mercado Pago, a fim de obter mais segurança no recebimento das suas notificações. Veja abaixo como configurar essa validação.
+
+1. Extraia o _timestamp_ (`ts`) e a assinatura do _header_ `x-signature`. Para isso, divida o conteúdo do _header_ pelo caractere `,`, o que resultará em uma lista de elementos. 
+2. Em seguida, divida cada elemento da lista pelo caractere `=`, o que resultará em um par de prefixos e os valores. O valor para o prefixo `ts` é o _timestamp_ da notificação e `v1` é a assinatura encriptada.
+3. Utilizando o _template_ abaixo, substitua os parâmetros pelos dados recebidos na sua notificação. 
+
+```template
+post;[urlpath];data.id=[data.id_url];type=[topic_url];user-agent:mercadopago webhook v1.0;[timestamp];action:[json_action];api_version:[json_apiversion];date_created:[json_datecreated_RFC3339];id:[id_json];live_mode:[livemode_json];type:[type_json];user_id:[userid_json];
+```
+
+No _template_, os valores englobados por `[]` devem ser trocados pelos valores da notificação, como:
+
+- Parâmetros com sufixo `_url` são provenientes de _query params_. Exemplo: `[topic_url]` será substituido pelo valor `payment` (sem os colchetes).
+- Parâmetros com sufixo `_json` são provenientes do _body_ da requisição.
+- `[urlpath]` será somente o domíno + o _path_ da URL (sem "http://" ou "https://").
+- `[timestamp]` será o valor `ts` extraído do _header_ `x-signature`.
+
+> Caso algum dos valores apresentados no _template_ abaixo não esteja presente em sua notificação, você deverá removê-los do template.
+
+4. No [Painel do desenvolvedor](/developers/panel/app), selecione a aplicação integrada, navegue até a seção Webhooks e **revele a assinatura secreta** gerada.
+5. Gere a contra chave para validação. Para isso, calcule um [HMAC](https://pt.wikipedia.org/wiki/HMAC) com a função de `hash SHA256` em base hexadecimal, utilize a **assinatura secreta** como chave e o _template_ populado com os valores como mensagem. Exemplo:
+
+[[[
+```php
+$cyphedSignature = hash_hmac('sha256', $data, $key);
+```
+```node
+const crypto = require('crypto');
+const cyphedSignature = crypto
+    .createHmac('sha256', secret)
+    .update(signatureTemplateParsed)
+    .digest('hex'); 
+```
+```java
+String cyphedSignature = new HmacUtils("HmacSHA256", secret).hmacHex(signedTemplate);
+```
+```python
+import hashlib, hmac, binascii
+
+cyphedSignature = binascii.hexlify(hmac_sha256(secret.encode(), signedTemplate.encode()))
+```
+]]]
+
+6. Por fim, compare a chave gerada com a chave extraída do cabeçalho, considerando elas devem ter uma correspondência exata. Além disso, é possível usar o _timestamp_ extraído do _header_ para comparação com um _timestamp_ gerado na hora do recebimento da notificação, a fim de estipular uma tolerância de atraso no recebimento da mensagem.
 
 ### Simular o recebimento da notificação
 
@@ -290,6 +345,7 @@ curl -X POST \
 > <br/>
 > No caso dos eventos de `delivery` e `topic_claims_integration_wh`, também teremos alguns atributos diferentes na resposta. Veja na tabela abaixo quais são essas particularidades.
 
+
 ```json
 {
  "id": 12345,
@@ -304,7 +360,6 @@ curl -X POST \
  }
 }
 ```
-
 Isso indica que foi criado o pagamento **999999999** para o usuário **44444** em modo de produção com a versão V1 da API e que esse evento ocorreu na data **2016-03-25T10:04:58.396-04:00**.
 
 | Atributo | Descrição |

guides/sdks-v2/official/java/create-payments.en.md

@@ -18,6 +18,8 @@ MPRequestOptions requestOptions = MPRequestOptions.builder()
     .customHeaders(customHeaders)
     .build();
 
+MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");
+
 PaymentClient client = new PaymentClient();
 
 List<PaymentItemRequest> items = new ArrayList<>();

guides/sdks-v2/official/java/create-payments.es.md

@@ -18,6 +18,8 @@ MPRequestOptions requestOptions = MPRequestOptions.builder()
     .customHeaders(customHeaders)
     .build();
 
+MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");
+
 PaymentClient client = new PaymentClient();
 
 List<PaymentItemRequest> items = new ArrayList<>();

guides/sdks-v2/official/java/create-payments.pt.md

@@ -18,6 +18,8 @@ MPRequestOptions requestOptions = MPRequestOptions.builder()
     .customHeaders(customHeaders)
     .build();
 
+MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");
+
 PaymentClient client = new PaymentClient();
 
 List<PaymentItemRequest> items = new ArrayList<>();