Utilizando webhooks

O que são webhooks

Webhooks são um recurso poderoso que podem ser utilizados para automatizar seus casos de uso e otimizar a sua integração. Através de um webhook é possível assinar um ou mais eventos de produto e a medida que os eventos acontecem sua integração pode ser notificada ativamente com mensagens HTTP.

Webhook endpoint

O endpoint de webhook é o endereço que será utilizado pela sua integração para ser notificada dos eventos que ela assina. E endpoint de webhook deve estar preparado para receber uma mensagem HTTP com o método POST.

POST https://example.com/notifications

Eventos

Um evento de webhook representa a notificação enviada pelo produto. Cada produto pode enviar diferentes tipos de eventos contendo dados sobre o processo de negócio que está sofrendo modificações.

Um evento de webhook contém a seguinte estrutura:

Atributo	Tipo	Descrição
webhookId	guid	Id do webhook que está recebendo a notificação.
event	string	Tipo do evento que está sendo notificado.
data	objeto	Um objeto com os dados associados ao evento. A estrutura do objeto é definida pelo tipo de evento que está sendo notificado.

No exemplo de notificação abaixo, o objeto data é definido pelo tipo de evento transactions.debit que indica um evento de débito na conta digital.

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        "accountId": "37297902000141-208-50-003886850",
        "date": "2022-03-02T22:01:55.274Z",
        "creditDebitIndicator": "DEBIT",
        "amount": 30900,
        "currency": "BRL",
        "transactionId": "33449743"
    }
}

Recebendo webhooks

Quando você configura um endpoint de webhook, você irá receber as notificações para os tipos de eventos escolhidos. Como você recebe essas notificações e responde a elas, via códigos de status HTTP, irá determinar o estado subsequente da assinatura.

Status Code	Descrição	Ação
200	Sucesso	O webhook foi entregue com sucesso.
410	Gone	Quando um código de status 410 é recebido, nós assumimos que o endpoint de webhook não está mais disponível. O webhook será desativado e não receberá mais novas notificações.
5XX	Servidor cliente indisponível	Novas tentativas de entrega serão feitas, incrementando 5 minutos de espera a cada tentativa. No máximo 5 tentativas de entrega serão feitas e caso não tenha sucesso em nenhuma delas, a notificação será salva em uma fila de mensagens com falha de entrega que pode ser acessada no painel de gestão de webhooks. As mensagens podem ser re-enfileiradas para entrega manualmente.

Autenticação

Quando o webhook é criado, uma chave de autenticação é gerada e disponibilizada no painel de gestão do webhook. Essa chave será enviada em cada notificação para o webhook, via o header Authorization. O seu servidor cliente deve utilizar essa chave para autenticar a notificação recebida.

Exemplo de mensagem de webhook

POST /notifications HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer ba143409-d498-4ac4-a6ae-b97d44a19e3f

{
    "webhookId": "bb2ae4c5-8094-4f3c-b0e0-02646ba6e5e3",
    "event": "transactions.debit",
    "data": {
        "accountId": "37297902000141-208-50-003886850",
        "date": "2022-03-02T22:01:55.274Z",
        "creditDebitIndicator": "DEBIT",
        "amount": 30900,
        "currency": "BRL",
        "transactionId": "33449743"
    }
}