Webhooks

O que são webhooks?

Webhooks são recursos para trocar informações entre dois sistemas no momento de um evento com mensagens HTTP. Eles podem ser usados para automatizar tarefas ao assinar eventos de produtos, que notificam a sua integração. Na Área de Desenvolvedor, você pode acessar os webhooks de cada aplicativo.

Webhook endpoint

O endpoint de webhook é o endereço usado pela sua integração para ser notificada dos eventos que ela assina. Para prepará-lo para receber mensagens HTTP, use o método POST.

POST https://example.com/notifications

Eventos

Eventos de webhook são as notificações enviadas pelo produto sobre algum processo que está acontecendo.

Um evento de webhook contém esta estrutura:

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

Neste exemplo, o objeto data é definido pelo tipo de evento transactions.debit, indicando um 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"
    }
}

x-correlation-id

O webhook virá com o campo x-correlation-id no header. O valor do x-correlation-idé o mesmo em toda nova tentativa.

Criando um webhook

No Portal Developers, acesse o app já configurado e clique no botão webhooks.

Clique em novo, insira a URL que receberá o webhook e selecione os eventos.

O webhook criado será listado no seu app.

Recebendo webhooks

Ao configurar um endpoint, você receberá notificações para os tipos de evento escolhidos. A assinatura será determinada pela forma que você recebe e responde a elas via status HTTP.

Status Code	Descrição	Ação
200	Sucesso	Webhook entregue.
410	Gone	Endpoint do webhook indisponível. O webhook será desativado e não receberá mais novas notificações.
5XX	Servidor cliente indisponível	2 novas tentativas serão feitas, com incrementos de 2 minutos de espera a cada uma delas (2 minutos e 4 minutos). Caso não seja entregue, a notificação será salva na fila de mensagens com falha, podendo ser acessada pelo painel de gestão de webhooks e entregue manualmente.

*O aplicativo tem 10 segundos para responder um webhook antes da mensagem falhar.

Autenticação

Quando um webhook é criado, a chave de autenticação é gerada e pode ser acessada no painel de Webhooks. Ela será enviada em cada notificação para o webhook pelo header Authorization e o seu servidor cliente deve usá-la para autenticar a notificação.

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"
    }
}

Novas tentativas

Após um erro, o webhook virá com o campo correlation-idcom um código que não irá mudar