Webhooks
notificações em tempo real sobre produtos na sua integração
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:
| 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.
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.
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 9 months ago