Pular para o conteúdo principal

Webhooks

Esta seção reúne endpoints para gerenciamento de notificações por parte do PSP recebedor a pessoa usuária recebedora.


Entendendo o padrão mTLS

Por norma do Banco Central, será necessário a inserção de uma chave pública da Efí em seu servidor para que a comunicação obedeça o padrão mTLS. No domínio que representa o seu servidor, você deverá configurar a exigência da chave pública (mTLS) que estamos disponibilizando, para que ocorra a autenticação mútua.

A Efí irá fazer 2 requisições para o seu domínio (servidor):

  1. Primeira Requisição: Vamos certificar que seu servidor esteja exigindo uma chave pública da Efí. Para isso, enviaremos uma requisição sem certificado e seu servidor não deverá aceitar a requisição. Caso seu servidor responda com recusa, enviaremos a 2ª requisição.
  2. Segunda Requisição: Seu servidor, que deve conter a chave pública disponibilizada, deverá realizar o "Hand-Shake" para que a comunicação seja estabelecida.

É necessário que o seu servidor tenha a versão mínima do TLS 1.2.

Em seu servidor, configure uma rota 'POST' com uma resposta padrão como uma string "200". Inclua o nosso certificado de produção ou homologação em seu servidor, a seguir temos alguns exemplos.

Servidores dedicados

Recomenda-se que você tenha um servidor dedicado para conseguir realizar as configurações do webhook, pois é necessário ter acesso a alguns arquivos para realizar as configurações, como nos exemplos abaixo.


Exemplos de configurações de servidor

Para configurar seu servidor, você precisará das chaves públicas da Efí. Abaixo estão os endereços das chaves para os ambientes de Produção e Homologação. Essas chaves devem ser baixadas e dispostas em seu servidor.

AtributoURL da chave pública
Produçãohttps://pix.gerencianet.com.br/webhooks/chain-pix-prod.crt
Homologaçãohttps://pix.gerencianet.com.br/webhooks/chain-pix-sandbox.crt

Os trechos de código abaixo buscam exemplificar as configurações necessárias em seu servidor para que seja possível realizar o hand-shake com nossos servidores.

from flask import Flask, jsonify, request
import ssl
import json
app = Flask(__name__)

@app.route("/", methods=["POST"])
def imprimir():
response = {"status": 200}
return jsonify(response)


@app.route("/pix", methods=["POST"])
def imprimirPix():
imprime = print(request.json)
data = request.json
with open('data.txt', 'a') as outfile:
outfile.write("\n")
json.dump(data, outfile)
return jsonify(imprime)

if __name__ == "__main__":
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.verify_mode = ssl.CERT_REQUIRED
context.load_verify_locations('caminho-certificados/certificado-público.crt')
context.load_cert_chain(
'caminho-certificados/server_ssl.crt.pem',
'caminho-certificados/server_ssl.key.pem')
app.run(ssl_context=context, host='0.0.0.0')
#Desenvolvido pela Consultoria Técnica da Efí

Para ter um ter um SSL válido, você deve entrar em contato com uma Autoridade Certificadora e gerar a chave privada server_ssl.key.pem e uma pública server_ssl.crt.pem, assim você valida a integridade da conexão. Você consegue realizar isso de forma gratuita utilizando um utilitário como o Certbot por exemplo.

Skip-mTLS

Para hospedagem em servidores compartilhados, pode haver restrições em relação à inserção de certificados gerados por outra entidade, como o nosso CA, por exemplo. Por isso, disponibilizamos a opção skip mTLS, que permite o cadastro do webhook sem a necessidade de validação mTLS.

É importante destacar que sempre enviaremos o certificado nos webhooks, seja no cadastro ou na notificação de Pix. No entanto, quando o skip-mTLS é utilizado, você, pessoa integradora, fica responsável por validar o nosso certificado.

Caso opte por utilizar o atributo skip mTLS, ou seja, sem a validação mTLS no seu servidor, você deverá implementar medidas para garantir que quem está enviando os webhooks ao seu servidor é, de fato, a Efí. Sugerimos as duas formas de validação a seguir, mas recomendamos fortemente que as utilize em conjunto:

  • Verifique o IP de comunicação: Você pode restringir a comunicação ao domínio do webhhook cadastrado para aceitar apenas mensagens do IP utilizado pela Efí.
  • IP utilizado atualmente em nossas comunicações: '34.193.116.226'.
  • Adicione uma hash à URL cadastrada no webhook: Crie um hmac (uma identificação própria) que será acrescentado ao final da URL no momento do cadastro do webhook. Essa hash será utilizada para validar a origem da notificação. Assim, todos os webhooks enviados ao seu servidor terão essa identificação final e sua aplicação deve validar a presença da mesma.
    Exemplo:
    URL de notificação original: https://seu_dominio.com.br/webhook
    Como deverá ser cadastrada com a hash: https://seu_dominio.com.br/webhook?hmac=xyz&ignorar=. O termo ignorar= servirá para tratar a adição do /pix no final da URL.

Como cadastrar o skip-mTLS:

Para configurar o webhook Pix, você deve utilizar o endpoint específico e passar no cabeçalho da requisição o parâmetro x-skip-mtls-checking com o valor true ou false dependendo se deseja habilitar ou desabilitar essa funcionalidade.

A imagem abaixo mostra como este parâmetro deve ser informado:


Configurar o webhook Pix

Endpoint para configuração do serviço de notificações acerca de Pix recebidos. Pix oriundos de cobranças estáticas só serão notificados se estiverem associados a um txid.

Lembrete

Uma URL de webhook pode estar associada a várias chaves Pix.

Por outro lado, uma chave Pix só pode estar vinculada a uma única URL de webhook.


PUT /v2/webhook/:chave
Requer autorização para o escopo: webhook.write


Requisição

{
"webhookUrl": "https://exemplo-pix/webhook"
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

Webhook para notificações acerca de Pix recebidos associados a um txid.

Exibir informações do webhook Pix

Endpoint para recuperação de informações sobre o webhook pix.

GET /v2/webhook/:chave
Requer autorização para o escopo: webhook.read


Respostas

As respostas abaixo representam Sucesso(200) do consumo.

{
"webhookUrl": "https://gn-pix-webhook.gerencianet.com.br/webhook/",
"chave": "40a0932d-1918-4eee-845d-35a2da1690dc",
"criacao": "2020-11-11T10:15:00.358Z"
}

Consultar lista de webhooks

Endpoint para consultar webhooks associados a chaves através de parâmetros como início e fim. Os atributos são inseridos como query params.

GET /v2/webhook
Requer autorização para o escopo: webhook.read


Requisição

O trecho abaixo mostra como os parâmetros inicio e fim (obrigatórios) devem ser repassados na requisição.

/v2/webhook/?inicio=2020-10-22T16:01:35Z&fim=2020-10-23T16:01:35Z

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
"parametros": {
"inicio": "2021-01-22T16:01:35.000Z",
"fim": "2022-12-30T16:01:35.000Z",
"paginacao": {
"paginaAtual": 0,
"itensPorPagina": 100,
"quantidadeDePaginas": 1,
"quantidadeTotalDeItens": 5
}
},
"webhooks": [
{
"webhookUrl": "https://seudominio.com.br/gn/webhook/",
"chave": "40a0932d-1618-4eee-845d-35a2da1590dc",
"criacao": "2021-05-05T19:52:13.000Z"
},
{
"webhookUrl": "https://.projetosseudominio.seudominio.com.br/gn/webhook/",
"chave": "40a0932d-1918-0eee-845d-35a2da1690dc",
"criacao": "2021-10-18T14:42:41.000Z"
},
{
"webhookUrl": "https://seudominio.com.br/webhook/?ignorar=",
"chave": "40a0032d-1918-45ee-845d-3562da1690dc",
"criacao": "2021-11-03T12:25:15.000Z"
}
]
}

Cancelar o webhook Pix

Endpoint para cancelamento do webhook pix.

DELETE /v2/webhook/:chave
Requer autorização para o escopo: webhook.write


Respostas

A resposta abaixo representa Sucesso(204) do consumo.

Webhook para notificações Pix foi cancelado.

Recebendo Callbacks

Esse serviço está protegido por uma camada de autenticação mTLS. Os callbacks são enviados pela Efí via POST url-webhook-cadastrada​/pix quando há uma alteração no status do Pix.

Informação

Para testar os endpoints de cobrança Pix Cob em ambiente de homologação, é possível simular todos os status retornados pela nossa API e webhook.

Cobranças com valor entre R$ 0.01 à R$ 10.00 são confirmadas, e você receberá a informação via Webhook.
Cobranças com valor acima de R$ 10.00 permanecem ativas, sem confirmação, e não há webhook nesses casos.


Requisição