Skip to content

Commit

Permalink
docs(webhook): deprecate 'evento' field on webhook test (#790)
Browse files Browse the repository at this point in the history
  • Loading branch information
noghartt committed Jan 23, 2024
1 parent 1337c85 commit 7c748cc
Show file tree
Hide file tree
Showing 5 changed files with 114 additions and 13 deletions.
5 changes: 3 additions & 2 deletions docs/integrations/oneclick.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ A primeira chamada será uma teste, para identificar se o seu endpoint existe e
```json
{
"data_criacao": "2023-07-12T13:58:06.821Z",
"evento": "teste_webhook"
"evento": "teste_webhook",
"event": "OPENPIX:TRANSACTION_RECEIVED"
}
```

Expand All @@ -53,7 +54,7 @@ curl -X 'POST' \
-H 'x-openpix-authorization: ' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-d $'{"data_criacao":"2023-07-12T13:58:06.821Z","evento":"teste_webhook"}'
-d $'{"data_criacao":"2023-07-12T13:58:06.821Z","evento":"teste_webhook","event":"OPENPIX:TRANSACTION_RECEIVED"}'
```

#### 4.2. Segunda chamada
Expand Down
11 changes: 4 additions & 7 deletions docs/sdk/php/frameworks/laravel/receiving-webhooks.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,6 @@ class WebhookController extends Controller
{
const SIGNATURE_HEADER = "x-webhook-signature";

const TEST_WEBHOOK_EVENT = "teste_webhook";

const OPENPIX_CHARGE_COMPLETED_EVENT = "OPENPIX:CHARGE_COMPLETED";

public function __construct(private Client $openpix)
Expand Down Expand Up @@ -172,7 +170,6 @@ Cada requisição irá trazer consigo um parâmetro `event` contendo o tipo do w
- `OPENPIX:MOVEMENT_CONFIRMED` - Pagamento confirmado é quando a transação do pix referente ao pagamento é confirmada.
- `OPENPIX:MOVEMENT_FAILED` - Falha no pagamento é quando o pagamento é aprovado e ocorre um erro.
- `OPENPIX:MOVEMENT_REMOVED` - O pagamento foi removido por um usuário.
- `teste_webhook`: Enviado pela plataforma para testar seu webhook.

Assumindo que você tenha um método `handleWebhook` que recebe todos os webhooks com a assinatura validada, veja o exemplo:

Expand Down Expand Up @@ -240,7 +237,8 @@ private function isChargePaidPayload(Request $request)

Ao configurar uma nova integração via webhooks na plataforma, ela enviará um webhook de teste para verificar se tudo está correto com sua aplicação.

Esse webhook de teste apresenta uma exceção durante a validação, onde o campo enviado é nomeado como `evento` em vez de `event`, com o valor `teste_webhook`.
Esse webhook de teste será enviado com o campo `event` contendo o valor especificado pelo evento selecionado na plataforma.
Por exemplo, se você selecionar o evento `Cobrança paga`, o campo `event` será `OPENPIX:CHARGE_COMPLETED`.

Veja como é possível verificar se um webhook é de teste:

Expand All @@ -253,10 +251,9 @@ Veja como é possível verificar se um webhook é de teste:
*/
private function isTestPayload(Request $request)
{
$event = $request->input("evento");
$event = $request->input("event");

// self::TEST_WEBHOOK_EVENT = "teste_webhook"
return ! empty($event) && $event === self::TEST_WEBHOOK_EVENT;
return ! empty($event) && $event === self::OPENPIX_CHARGE_COMPLETED_EVENT;
}
```

Expand Down
59 changes: 59 additions & 0 deletions docs/webhook/webhook-events-type.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: "Tipos de eventos do Webhook"
description: "Tipos de eventos do Webhook"
tags:
- webhook
---

## Tipos de eventos do Webhook

O Webhook é um recurso que permite que a OpenPix envie notificações para sua aplicação quando um evento ocorre.
Por exemplo, quando uma cobrança é paga, a OpenPix envia uma notificação para o seu servidor.

Abaixo, você pode ver uma lista de todos os eventos que a OpenPix envia para sua aplicação.

## Eventos de cobrança

Os eventos de cobrança são enviados quando uma cobrança é paga.

### OPENPIX:CHARGE_COMPLETED

Esse evento é enviado quando uma cobrança é paga.

### OPENPIX:CHARGE_EXPIRED

Esse evento é enviado quando uma cobrança expira.

### OPENPIX:CHARGE_CREATED

Esse evento é enviado quando uma cobrança é criada.

### OPENPIX:CHARGE_COMPLETED_NOT_SAME_CUSTOMER_PAYER

Esse evento é enviado quando uma cobrança é paga com um `payer` diferente do `customer`.

## Eventos de transação

Os eventos de transação são enviados quando uma transação é recebida.

### OPENPIX:TRANSACTION_RECEIVED

Esse evento é enviado qunado uma transação é recebida, seja ela de uma cobrança ou de um QR code estático.

### OPENPIX:TRANSACTION_REFUND_RECEIVED

Esse evento é enviado quando é realizado o reembolso de uma transação.

## Eventos de Pagamento Instantâneo

### OPENPIX:MOVEMENT_CONFIRMED

Esse evento é enviado quando um pagamento é confirmado.

### OPENPIX:MOVEMENT_FAILED

Esse evento é enviado quando um pagamento confirmado falha.

#### OPENPIX:MOVEMENT_REMOVED

Esse evento é enviado quando um pagamento é removido.
15 changes: 11 additions & 4 deletions docs/webhook/webhook-hmac.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ defaultValue="PHP"
```php
<?php
$headers['X-OpenPix-Signature'] = 'jgR2XF0PKDiAwHP1s+TryvxMySQ='; // vira da chamada do webhook
$body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook"}'; // vira da chamada do webhook
$body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}'; // vira da chamada do webhook

$secretKeyOnOpenpixPlatform = 'hmac-secret-key'; // secret key da chave de acesso do OpenPix

Expand Down Expand Up @@ -71,7 +71,7 @@ defaultValue="PHP"

const openpixSignatureHeader = 'jgR2XF0PKDiAwHP1s+TryvxMySQ='; // vem da chamada do webhook

const body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook"}'; // vem da chamada do webhook
const body = '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}'; // vem da chamada do webhook

const key = 'hmac-secret-key'; // secret key da chave de acesso do OpenPix

Expand All @@ -91,11 +91,18 @@ defaultValue="PHP"

```bash

echo -n '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook"}' | openssl dgst -sha1 -hmac "hmac-secret-key" -binary | base64
echo -n '{"data_criacao":"2021-08-10T20:32:14.429Z","evento":"teste_webhook","event":"OPENPIX:CHARGE_COMPLETED"}' | openssl dgst -sha1 -hmac "hmac-secret-key" -binary | base64

```
</TabItem>
</Tabs>

:::info

O campo `event` enviado junto ao payload do webhook tem seu valor conforme o tipo de evento que você escolheu no momento em que criou o webhook.
Para saber mais sobre os tipos de eventos, acesse a [documentação de eventos](./webhook-events-type).

:::

Nesse link temos um exemplo de validação do HMAC usando JavaScript
[WebhookPost](https://github.com/Open-Pix/node-backend-integration/blob/master/src/webhook/webhookPost.ts)
37 changes: 37 additions & 0 deletions docs/webhook/webhook-test.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
title: "Validando o webhook de teste"
tags:
- webhook
- test
---

## Validando o webhook de teste

Quando é criado um novo webhook, a OpenPix envia uma requisição de teste para o seu endpoint.
Essa requisição é enviada para garantir que o seu endpoint está funcionando corretamente.

### 1. Recebendo o webhook de teste

Quando a OpenPix envia um webhook de teste, o corpo da requisição é:

```json
{
"data_criacao":"2024-01-23T20:32:14.429Z",
"event":"OPENPIX:CHARGE_COMPLETED",
}
```

:::info

O campo `event` é o tipo de evento que está sendo enviado. Ele é escolhido conforme o evento selecionado na plataforma.
Você pode olhar os tipos de eventos disponíveis [aqui](./webhook-events-type.md).

:::

### 2. Respondendo o webhook de teste

Para responder o webhook de teste, basta retornar o status code `200` e o corpo da resposta vazio.

```php
return response()->json([], 200);
```

0 comments on commit 7c748cc

Please sign in to comment.