Skip to main content
Este guia mostra como criar uma assinatura de webhook no painel administrativo, proteger as chamadas e acompanhar as entregas realizadas pela BonifiQ.

​
Criar uma Assinatura

1

Abra o Menu Empresa

No canto superior direito do painel administrativo, abra o menu Empresa.
2

Acesse a Área de API

Selecione API para abrir a página Credenciais de API.
3

Inicie a Criação

Clique no botão CREDENCIAL DE API.
4

Selecione Webhook

Escolha a opção Webhook. O painel abrirá a aba de Webhooks e exibirá o formulário Novo Webhook.
5

Configure a Assinatura

Preencha os campos, selecione ao menos um tópico e adicione um header secreto para autenticar as chamadas.
6

Salve

Clique em Salvar. Se a opção Ativado estiver marcada, a assinatura começará a receber novos eventos dos tópicos selecionados.

​
Campos do Formulário

Define se a assinatura pode receber eventos.
  • Marcado: novos eventos podem ser enviados ao endpoint.
  • Desmarcado: a assinatura permanece salva, mas fica pausada.
Nome usado para identificar a integração na lista de assinaturas e no histórico de eventos.Exemplos: Sincronização ERP, Pedidos para o CRM ou Eventos de Pontos.
Endereço público que receberá as chamadas.
Use HTTPS com certificado válido e não exponha a URL em código ou logs públicos.
A tela permite selecionar POST, GET, PUT, PATCH ou DELETE. Use POST por padrão, salvo quando o contrato do seu endpoint exigir outro método.
Selecione um ou mais eventos que devem chamar o endpoint. A assinatura receberá apenas eventos ocorridos depois de estar ativa.Consulte os payloads de comunicações, pontos, pedidos, afiliados e clientes.
Endereço que receberá notificações quando uma sequência de falhas desativar a assinatura. Use uma caixa monitorada pela equipe responsável pela integração.
Headers estáticos adicionados a todas as chamadas. Use-os para autenticação ou roteamento.
Os valores são enviados exatamente como configurados. A BonifiQ não adiciona uma assinatura HMAC nativa ao payload; seu endpoint deve validar o segredo compartilhado.
Ative apenas quando o sistema de destino não puder consumir o envelope padrão.O template pode usar propriedades existentes no payload do tópico selecionado:
Os campos disponíveis variam por tópico. Consulte a página do evento antes de criar o template.
O corpo personalizado substitui completamente o envelope padrão. Uuid, Timestamp, Topic e TopicName não são adicionados automaticamente ao template. Prefira o envelope padrão quando precisar deduplicar entregas pelo identificador do evento.

​
Variáveis na URL

A URL também pode usar valores do payload específico do tópico:
Se uma propriedade não existir naquele tipo de evento, a URL não poderá ser montada como esperado. Use apenas campos documentados para todos os tópicos selecionados na assinatura.

​
Gerenciar Assinaturas

Na aba Webhooks, a lista mostra o nome, os tópicos e o status de cada assinatura.

Editar

Altere URL, método, tópicos, e-mail, headers ou corpo personalizado.

Ativar ou Pausar

Abra Editar, marque ou desmarque Ativado e salve a assinatura.

​
Acompanhar Entregas

A seção Últimos eventos enviados apresenta:
  • nome do webhook e tópico;
  • data do último envio;
  • quantidade de tentativas;
  • status da entrega;
  • payload em Ver detalhes;
  • mensagem técnica em Ver Erro, quando houver falha.
Use esse histórico para investigar erros, confirmar o formato enviado e decidir quando reativar uma assinatura corrigida.

​
Requisitos do Endpoint

1

Disponibilize uma URL Segura

Use um endpoint público com HTTPS e certificado válido.
2

Valide a Autenticação

Compare o header secreto antes de aceitar o payload.
3

Implemente Idempotência

Registre o Uuid do envelope padrão em armazenamento durável. O mesmo identificador é reutilizado nas retentativas.
4

Salve e Enfileire

Persista o evento ou coloque-o em uma fila antes de iniciar o processamento de negócio.
5

Responda Rapidamente

Retorne HTTP 2xx depois de confirmar o recebimento. A BonifiQ aguarda no máximo 30 segundos, mas o ideal é responder em poucos segundos.
Consulte as garantias de entrega para entender retentativas, backoff, respostas permanentes e desativação automática.