Documentação para Desenvolvedores

Webhooks

Webhooks permitem que sistemas externos recebam notificações de todos os eventos que ocorrem no sistema. Quando um evento acontece, o sistema envia uma requisição HTTP POST para a URL configurada no webhook com as informações relativas ao evento. Ao receber a notificação, o sistema pode executar diversas tarefas, dependendo do objetivo da integração.

Os webhooks também são chamados de Callbacks ou Reverse API.

Funcionamento

Quando um evento é disparado dentro do Boleto Simples, são geradas notificações para cada webhook que esteja configurado para receber o tal evento. Essas notificações geram automaticamente uma requisição que é realizada na URL configurada no webhook. O Boleto Simples mantém o registro de todas as requisições geradas, bem como as informações da requisição (Request) e da resposta do servidor externo (Response).

Requisição

Além dos cabeçalhos normais de uma requisição HTTP POST, os seguintes cabeçalhos são enviados:

Cabeçalho Descrição
X-BoletoSimples-Event Código do evento que gerou essa notificação.
X-BoletoSimples-Delivery-Id ID único da notificação, no formato UUID.
X-BoletoSimples-Environment Ambiente de onde a notificação
foi disparada (production ou sandbox).
X-Hub-Signature Assinatura de segurança, para você verificar
que a chamada saiu realmente dos servidores
do Boleto Simples.

Exemplo de requisição:

POST /15a0nqn1 HTTP/1.1

Host: requestb.in
X-Boletosimples-Delivery-Id: 94d4eab5-787a-4209-8282-5bc1398575ab
X-Hub-Signature: sha1=bb8ed09391796e2f89b0c42aa0dec9b6d28cafc5
Total-Route-Time: 0
X-Request-Id: 8ed758bd-3351-4724-aaa6-2ad550c3f0c7
User-Agent: BoletoSimples-Robot (sandbox)
Content-Type: application/json
X-Boletosimples-Event: ping
Via: 1.1 vegur
Content-Length: 77
Connect-Time: 1
Connection: close
X-Boletosimples-Environment: sandbox

{
  "event_code": "ping",
  "webhook": {
    "id": 1,
    "url": "http://requestb.in/15a0nqn1"
  }
}

Resposta

O servidor espera uma resposta positiva, ou seja, com o Status Code 2xx. Caso não esteja familiarizado com isso, leia sobre HTTP Status Codes.

Todas as outras informações retornadas no cabeçalho ou no conteúdo da resposta são ignoradas, porém são armazenadas. Nós guardamos os cabeçalhos e o conteúdo da resposta. Por esse motivo é importante que nenhuma informação sigilosa seja retornada nas requisições de notificação dos webhooks.

O Boleto Simples não tem implementado ainda a retentativa de entrega caso o seu servidor retorne um erro. A requisição de notificação é enviada somente uma única vez. Mesmo que o seu servidor retorne algum erro, a requisição não é feita novamente.