Webhooks

🚧

Webhook Sandbox

No momento, a funcionalidade de webhooks no ambiente de sandbox se encontra em desenvolvimento e, portanto, não está disponível para todos os usuários.

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. O endpoint deve atender a alguns requisitos:

• Estar em conformidade com o protocolo https;
• Não estar acompanhado de portas customizadas. Nosso servidor realizará requisições apenas para a porta padrão do protocolo https.

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:

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": {
        //payload do webhook 
    }
}

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.

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.

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

Consentimento

Por questões de segurança, seu endpoint receberá apenas os eventos referentes aos escopos de produto que fizeram parte de um fluxo de geração de token do seu aplicativo. Por exemplo, caso seu aplicativo tenha um webhook com os eventos de saldo e extrato assinados, porém, nunca realizou o fluxo de geração com estes token, o agent não enviara estes eventos para o seu endpoint.

Assim, caso não esteja recebendo um evento que possui assinado, certifique-se de realizar o fluxo de geração de token com o escopo referente ao produto que emite o evento.

Protocolo de retentativa

O protocolo de retentativa é uma forma de assegurar que instabilidades pontuais no seu sistema não impeçam o recebimento de webhooks.

Ao obter um status code da familia 4XX ou 5XX, o nosso agent tentará o reenvio do webhook mais três vezes dentro de 10 minutos. Caso não obtenha sucesso, o status code obtido na última tentativa será atrelado à tentativa de envio que ficará disponível no painel de gestão de webhooks, podendo ser reprocessada manualmente pelo usuário.

Tags

As tags no sistemas do BTG Pactual Empresas são pares de chave:valor que funcionam como identificadores nas responses de webhooks. São enviadas no payload dos eventos disparados pelo nosso sistema de modo a facilitar para você o gerenciamento dos eventos recebidos.

Exemplo de mensagem de webhook

POST /notifications HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer ba143409-d498-4ac4-a6ae-b97d44a19e3f
//O header authorization é preenchido com seu webhook secret

{
    "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.