Webhooks

notificações em tempo real sobre produtos na sua integração

Suggest Edits

🚧

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. 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:

AtributoTipoDescrição
webhookIdguidId do webhook que recebe a notificação.
eventstringTipo do evento notificado.
dataobjetoObjeto 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.

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 CodeDescriçãoAção
200SucessoWebhook entregue.
410GoneEndpoint do webhook indisponível. O webhook será desativado e não receberá mais novas notificações.
5XXServidor cliente indisponível2 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.

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

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

Updated 25 days ago