Utilizando webhooks
Receba notificações em tempo real sobre produtos conectados em sua integração
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"
}
}
Updated 3 months ago