Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt

Use this file to discover all available pages before exploring further.

​
O que são Webhooks?

Webhooks são uma maneira eficiente e automatizada de uma aplicação enviar dados em tempo real para outra aplicação. Eles permitem que sistemas diferentes comuniquem eventos específicos sem a necessidade de uma solicitação ativa da aplicação receptora. Em vez disso, a aplicação que gera o evento envia uma notificação, normalmente na forma de uma solicitação HTTP POST, para uma URL previamente configurada pela aplicação receptora.

​
O que os Webhooks fazem?

Os Webhooks são usados para notificar sua aplicação sobre eventos que ocorrem em outra aplicação ou serviço. Algumas das tarefas comuns realizadas por Webhooks incluem:
  • Notificações em Tempo Real: A aplicação receptora é imediatamente notificada quando algo acontece, como a criação de um novo pedido, uma mudança de status, ou uma nova mensagem.
  • Automação de Processos: Permitem automatizar respostas ou ações em sua aplicação quando certos eventos ocorrem, sem a necessidade de consultas constantes à API.
  • Integração entre Sistemas: Facilitam a integração entre sistemas diferentes, permitindo que eventos em um sistema desencadeiem ações automáticas em outro.

​
Como os Webhooks funcionam?

  1. Configuração: Primeiro, a aplicação receptora deve configurar um endpoint (uma URL pública) que estará pronto para receber as notificações via Webhook.
  2. Registro do Webhook: A aplicação emissora precisa ser configurada para enviar notificações para o endpoint do Webhook sempre que um evento específico ocorrer.
  3. Envio do Evento: Quando o evento configurado ocorre, a aplicação emissora envia uma solicitação HTTP POST para o endpoint do Webhook, incluindo no corpo da requisição os dados relevantes sobre o evento.
  4. Processamento do Evento: A aplicação receptora processa a informação recebida e pode executar várias ações em resposta ao evento, como atualizar um banco de dados, enviar um e-mail, ou disparar outro processo interno.

​
Tratamento de Falhas e Retentativas

Em um cenário ideal, a aplicação receptora recebe e processa a solicitação do Webhook sem problemas. No entanto, falhas podem ocorrer devido a vários fatores, como indisponibilidade do servidor, problemas de rede, ou erros de processamento. Para garantir que as notificações importantes não sejam perdidas, implementamos um mecanismo de retentativa. Se a aplicação receptora responder com um código de status HTTP maior que 400 (indicando um erro), a aplicação emissora tentará reenviar a notificação do Webhook até 5 vezes.

​
Detalhes da Retentativa

  • Critério de Falha: Qualquer resposta com código de status HTTP maior ou igual que 400.
  • Número de Retentativas: Até 5 tentativas.
  • Intervalo entre Retentativas: O intervalo entre cada retentativa aumenta progressivamente usando um fator de 2,5. Os intervalos em segundos são os seguintes:
    • 1ª Tentativa: 2,5 segundos (2.5^1)
    • 2ª Tentativa: ~6 segundos (2.5^2)
    • 3ª Tentativa: ~15 segundos (2.5^3)
    • 4ª Tentativa: ~39 segundos (2.5^4)
    • 5ª Tentativa: ~97 segundos (2.5^5)
    Cada intervalo é calculado como 2,5^n, onde n é o número da tentativa.

​
Cabeçalhos HTTP Personalizados

Todas as notificações de webhook enviadas pela Zapster API incluem cabeçalhos HTTP personalizados que identificam a origem e o contexto do evento. Esses cabeçalhos são úteis para validação, logging e configuração de regras de firewall.
CabeçalhoTipoDescriçãoExemploPresente em
X-Instance-IDstringID da instância que gerou o eventoinst_abc123Todas as notificações
X-Message-IDstringID único da notificaçãomsg_xyz789Todas as notificações
X-Webhook-IDstringID do webhook registradowhk_def456Quando webhook está registrado
X-Attempt-CountnumberNúmero da tentativa (1-5)1Todas as notificações
User-AgentstringIdentificador do emissorZapsterapi/1.2.3Todas as notificações

​
Validação e Allowlisting

Você pode utilizar os cabeçalhos HTTP personalizados para validar a origem das notificações recebidas. Abaixo, um exemplo em Node.js: 
app.post('/webhook', (req, res) => {
  const instanceId = req.headers['x-instance-id']
  const messageId = req.headers['x-message-id']
  const attemptCount = req.headers['x-attempt-count']

  console.log(`Notificação recebida da instância ${instanceId}`)
  console.log(`ID da mensagem: ${messageId}, tentativa: ${attemptCount}`)

  // Valide a origem antes de processar
  if (!instanceId) {
    return res.status(400).json({ error: 'Cabeçalho X-Instance-ID ausente' })
  }

  // Processe o evento
  const event = req.body
  console.log(`Evento: ${event.type}`, event.data)

  res.status(200).json({ received: true })
})
Allowlisting em WAF/Firewall: Se você utiliza um Web Application Firewall (WAF) ou regras de firewall, configure-o para aceitar requisições POST que contenham os cabeçalhos X-Instance-ID, X-Message-ID, X-Attempt-Count e User-Agent com o prefixo Zapsterapi/.