Gerenciamento de webhooks do Pix

Sabemos que não é possível garantir que seu servidor esteja 100% disponível para receber todos os gatilhos da API de Pix Celcoin. Pensando nisso, criamos um mecanismo de controle e gerenciamento dos webhooks que estão pendentes de envio, de forma que seu sistema não receba requisições em excesso quando ele não estiver preparado para isso.

Regra geral de controle

Basicamente, essa regra prevê o número máximo de tentativas de disparo do webhook, por evento ou transação que esteja com status pendente por determinado período de tempo.

Uma mensagem possui três possíveis status:

• Pendente: é o estado inicial da notificação e permanece até que sua aplicação retorne HTTP Status Code 200, quando ele será alterado para “Sucesso”, ou até que a regra de controle seja atingida e o status mudar para “Bloqueado”.
• Bloqueado: estado indicativo de que o limite de tentativas de notificação foi atingido. Até que seja feito o desbloqueio do evento/transação, o status não será alterado.
• Sucesso: status final. Ocorre quando a sua aplicação retorna http 200 informando que recebeu o webhook.

Bloqueio

O bloqueio pode ocorrer por dois fluxos:

• Bloqueio da transação: quando é realizado mais de 20 tentativas de notificação para determinada transação. Nesse cenário, a transação não terá nenhuma nova tentativa de envio de webhook até que seja feito o desbloqueio.
• Bloqueio do evento: ocorre quando é realizado mais de 50 tentativas de notificação de determinado evento, independente da transação. Nesse caso, pode haver uma ou mais transações que não serão notificadas, uma vez que o evento não será disparado até que seja feito o desbloqueio.

Os eventos de Pix são:
▫ ‏‏‏CONFIRMED: referente ao transactionType “PAYMENT” - StatusCode.description “Confirmed”
▫ ERROR: referente ao transactionType “PAYMENT” - StatusCode.description “Error”
▫ REVERTED: referente ao transactionType REVERTED
▫ PAID: referente ao transactionType RECEIVEPIX
▫ PAYMENT_REVERTED: referente ao transactionType REVERTPIX - StatusCode.description “Confirmed” e “Error”

Desbloqueio

O desbloqueio acontece automaticamente ao reenviar a notificação bloqueada.

Consultar bloqueios

Para saber se há bloqueio de notificações, é necessário realizar uma consulta na API de webhook, informando:

• evento: evento da transação
• dateFrom e dateTo: data inicial e data final, respectivamente. A API permite a consulta do que ocorreu em determinado dia. Por exemplo: dateFrom: 2022-05-14 e dateTo: 2022-05-15
• limit e start: limite e posição do item retornado, respectivamente. São parâmetros para paginação. A API retorna até 100 registros, portanto, se houver 140 registros, será necessário, pelo menos, duas consultas, uma com limit 100 e start 0 e outra com limit 100 (ou 40) e start 101.
• onlyPending: habilitar como true permite buscar o registro de apenas webhooks com status pendentes e bloqueados, excluindo assim os que já retornam sucesso (HTTP 200).

Conforme mencionado anteriormente, há bloqueio por transação e por evento. Ao realizar essa consulta, se o bloqueio ocorreu por transação, o campo eventStatus irá retornar como Ativo, mas, no objeto de WebhookDetails, o campo status retornará como Bloqueado. Caso seja um bloqueio por evento, o campo eventStatus retornará como Bloqueado.

Além dos eventos e/ou transações bloqueadas, essa API também permite consultar a fila de processamento, que são as notificações com status pendente, e também as notificações enviadas com sucesso.

📘

Recomendamos que uma nova consulta seja feita, após reenvio dos webhooks, para validar se os itens foram desbloqueados e reenviados com sucesso. A consulta deve levar em consideração a fila de processamento de reenvio, ou seja, quanto mais notificações disparadas, mais tempo pode demorar para que todas sejam reenviadas.

Modelo de requisição:

curl --location --request GET 'https://api.openfinance.celcoin.dev/webhook-manager-webservice/v1/webhook/CONFIRMED?dateTo=2022-05-23T16:28:51.535Z&dateFrom=2022-05-23T16:28:51.535Z&limit=50&start=0&onlyPending=true' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \

Modelo de resposta:

  {
    "version": "v1.0",
    "status": 200,
    "webhookEvent": "ERROR",
    "dateTo": "2022-09-20",
    "dateFrom": "2022-09-21",
    "totalFound": 0,
    "totalReturned": 0,
    "eventStatus": "Bloqueado",
    "webhookDetails": [
      {
        "endpoint": "www.api.com.br/teste",
        "status": "Bloqueado)",
        "transactionId": 12312331,
        "dateLastUpdate": "2022-09-21",
        "requestBody": "{\"RequestBody\":{\"TransactionType\":\"PAYMENT\",\"TransactionId\":4644372,\"StatusCode\":{\"StatusId\":2,\"Description\":\"Confirmed\"}}}",
        "statusCode": "200",
      }
    ]
  }

Estrutura do response

Reenviar webhooks por transação

Para desbloquear um webhook, basta reenviar as notificações que ficaram bloqueadas pela regra de controle. Na consulta anterior, serão retornadas todas as notificações que constam como "bloqueadas" e, então, deve ser usado o retorno da consulta para realizar o reenvio.

No caso do reenvio por transação, haverá disparo da notificação apenas para as transações cujos IDs sejam listados no body da requisição (transactionsToResend). Esse identificador pode ser obtido na consulta de eventos bloqueados.

Modelo de requisição:

curl --location --request POST 'https://api.openfinance.celcoin.dev/webhook-manager-webservice/v1/webhook/CONFIRMED' \
--header 'accept: application/json' \
--header 'Content-Type: application/json-patch+json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "transactionsToResend": [
    0
  ]
}'

Modelo de resposta:

{
    "version": "v1.0",
    "status": 200,
    "webhookEvent": "ERROR",
    "dateTo": "2022-10-04T18:19:54.199Z",
    "dateFrom": "2022-10-04T18:19:54.200Z"
  }

Estrutura do response

📘

O desbloqueio por transação é utilizado, principalmente, se o objetivo é liberar o disparo da notificação das transações selecionadas. Caso queira desbloquear um evento por completo, ou seja, todas as transações vinculadas a um evento, use a chamada de reenvio de _webhooks _por evento.

Reenviar webhooks por evento

Nesse cenário, deve ser informado o evento que deseja desbloquear e a data inicial e final desse disparo. Lembrando que, o intervalo dessas datas, pode ser de até 1 dia. Nessa requisição, se for informado o evento de PAID, por exemplo, todas as transações que estiverem bloqueadas com esse status terão o reenvio da notificação disparado, além de desbloquear o evento para transações futuras.

Modelo de requisição:

curl --location --request POST ''https://api.openfinance.celcoin.dev/webhook-manager-webservice/v1/webhook/CONFIRMED?dateTo=2022-05-23T16:28:51.535Z&dateFrom=2022-05-23T16:28:51.535Z' \
--header 'accept: application/json' \
--header 'Authorization: Bearer {access_token}' \

Modelo de resposta:

[
  {
    "version": "v1.0",
    "status": 200,
    "webhookEvent": "ERROR",
    "dateTo": "2022-06-06T18:07:08.781Z",
    "dateFrom": "2022-06-06T18:07:08.781Z"
  }
]

Tabela de erros

Segue lista de erros que podem ser apresentados no fluxo de gerenciamento de webhooks: