Integrações - Webhooks

O que é

Webhooks são notificações HTTP que o Viagilize envia automaticamente para um endpoint do seu sistema quando algo importante acontece - uma reserva é criada, um pagamento é confirmado, um cliente faz check-in, um contrato é assinado, entre outros. Em vez de o sistema externo precisar ficar consultando a API a cada minuto para descobrir novidades, ele recebe o evento na hora em que ele ocorre, com o payload completo no corpo da requisição.

Esta página é normalmente acessada pelo time técnico (ou pelo integrador parceiro) depois que um token de API já foi gerado. O fluxo típico é: o ERP/CRM/automação cadastra a URL dele aqui, escolhe os eventos que quer ouvir e configura no seu lado a validação da assinatura HMAC. A partir desse momento, qualquer ação no Viagilize que dispare um dos eventos selecionados gera um POST automático em fila dedicada (webhooks-api), com retries em caso de falha e log persistente de cada tentativa.

Como usar

1. Vá em Configurações > API no sidebar (URL /admin/configuracoes/api).
2. Clique na aba Webhooks.
3. Clique em Novo Webhook (botão azul no canto superior direito do cartão).
4. Preencha o modal:
   • Nome - rótulo interno para identificar a integração (ex.: "Notificações ERP"). Obrigatório, até 255 caracteres.
   • URL de Destino - endpoint HTTPS do seu sistema que receberá o POST. Obrigatório, validado como URL, até 500 caracteres.
   • Eventos para Notificar - marque pelo menos um evento. A lista é agrupada por recurso (Reservas, Pagamentos, Check-in, Excursões, Clientes, Contratos).
5. Clique em Criar Webhook. O secret (prefixo whsec_) é gerado automaticamente e exibido no card do webhook. Use o botão de prancheta para copiar o valor completo e armazene em local seguro no seu sistema.
6. Configure no destino a validação HMAC SHA256 com o header X-Viagilize-Signature. A partir do próximo evento elegível, seu endpoint começa a receber as notificações.

Eventos disponíveis

Grupo	Evento	Quando dispara
Reservas	reserva.criada	Nova reserva criada
Reservas	reserva.confirmada	Reserva confirmada (pagamento OK)
Reservas	reserva.cancelada	Reserva cancelada
Reservas	reserva.expirada	Reserva expirada por falta de pagamento
Pagamentos	pagamento.criado	Novo pagamento registrado
Pagamentos	pagamento.confirmado	Pagamento confirmado
Pagamentos	pagamento.estornado	Pagamento estornado
Check-in	checkin.realizado	Check-in realizado
Check-in	checkout.realizado	Check-out realizado
Excursões	excursao.publicada	Excursão publicada
Excursões	excursao.cancelada	Excursão cancelada
Clientes	cliente.criado	Novo cliente cadastrado
Contratos	contrato.assinado	Contrato assinado pelo cliente

Formato do payload

Cada requisição chega como POST em formato JSON, com a estrutura padronizada:

{
  "event": "reserva.criada",
  "event_id": "5f8b9d2c-1a2b-4c3d-9e0f-123456789abc",
  "created_at": "2026-05-16T12:34:56-03:00",
  "data": {
    "...": "campos específicos do evento"
  }
}

O campo event_id é um UUID gerado uma única vez por evento. Se a entrega for retentada (até 3 vezes), o mesmo event_id é reenviado - use essa chave para deduplicar no seu lado.

Headers enviados

Header	Valor
Content-Type	application/json
X-Viagilize-Signature	Assinatura HMAC SHA256 do corpo, prefixada com sha256=
X-Viagilize-Event	Nome do evento (ex.: reserva.criada)
User-Agent	Viagilize-Webhook/1.0

Validar a assinatura HMAC

O Viagilize assina cada corpo com hash_hmac('sha256', $payload, $secret) e envia o resultado no header X-Viagilize-Signature no formato sha256=<hex>. No seu endpoint, calcule a mesma assinatura usando o secret salvo na criação e compare com o header recebido. Exemplo em PHP:

$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $request->header('X-Viagilize-Signature'))) {
    abort(401);
}

Use sempre comparação tempo-constante (hash_equals) para evitar ataques de timing.

Testar um webhook

1. Na linha do webhook, clique no ícone de avião de papel (tooltip "Testar Webhook").
2. O Viagilize envia um POST síncrono com o evento test.ping e payload de exemplo.
3. O toast mostra "Webhook testado com sucesso!" ou a mensagem de erro retornada (timeout, HTTP 4xx/5xx, falha de conexão).
4. O resultado completo (status, tempo de resposta, corpo retornado) fica registrado em Logs > Webhooks.

Acompanhar entregas e falhas

Cada card de webhook mostra a URL, a data do último disparo, os primeiros 4 eventos inscritos e o status. Quando o destino retorna erro 5 ou mais vezes seguidas, aparece o badge vermelho N falhas consecutivas. Para histórico completo, abra a aba Logs, escolha a sub-aba Webhooks e use os filtros de período (24h, 48h, 7 dias, 30 dias) e status (Sucesso, Erro Cliente, Erro Servidor).

Casos especiais

Comportamento dentro de transações

Quando o evento é disparado durante uma transação de banco (ex.: criação de reserva que envolve várias tabelas), o WebhookService::dispatch espera o COMMIT para enfileirar o job (DB::afterCommit). Se a transação sofrer ROLLBACK, nenhum webhook é entregue - isso evita notificar parceiros de operações que não aconteceram de fato.

Retries automáticos

A entrega roda em job dedicado (DispatchWebhookJob) na fila webhooks-api com até 3 tentativas e backoff progressivo de 10, 30 e 60 segundos entre cada nova tentativa. O timeout HTTP de cada chamada é de 10 segundos. Se as 3 tentativas falharem, o evento entra no log com status failed e incrementa o contador failure_count do webhook.

Desativação automática após falhas

A cada falha de entrega o contador failure_count é incrementado e o badge vermelho aparece a partir de 5 falhas consecutivas. Quando atinge 10 falhas consecutivas, o webhook é desativado automaticamente (is_active = false) e para de receber novos eventos até ser reativado manualmente. Quando o destino volta a responder com sucesso, o contador é zerado.

Regenerar o secret

Use o ícone de seta circular na linha do webhook (tooltip "Regenerar Secret"). O sistema confirma que o secret atual deixará de funcionar e gera um novo valor whsec_.... Atualize a configuração de validação HMAC no destino antes do próximo disparo, senão todas as entregas começarão a ser rejeitadas com erro 401 no seu lado.

Editar URL, nome ou eventos

Use o ícone de lápis na linha do webhook para abrir o modal de edição. URL, nome e lista de eventos podem ser alterados sem regenerar o secret. Após salvar, os próximos disparos já usam a nova configuração.

Pausar sem excluir

O toggle de ativação na linha do webhook desliga o envio mantendo o cadastro e o secret. Útil para janelas de manutenção do sistema externo. Para reativar, basta clicar no toggle novamente.

Webhooks dos meios de pagamento de pagamento

Esta página gerencia os webhooks de saída (Viagilize → seu sistema). Os webhooks de entrada que os meios de pagamento (Mercado Pago, Asaas, Pagar.me, InfinitePay) enviam para o Viagilize são roteados internamente por app/Http/Controllers/Webhook/ e não precisam de configuração nesta página - eles já são processados automaticamente quando você ativa o meio de pagamento em Integrações > Meios de pagamento de Pagamento.

Erros comuns e como resolver

• "Selecione pelo menos um evento" - Causa: o formulário foi enviado sem nenhum evento marcado. Solução: marque ao menos um evento (ex.: reserva.criada) antes de salvar.
• "The url field must be a valid URL" - Causa: a URL de destino está vazia, sem protocolo (https://) ou com formato inválido. Solução: informe a URL completa começando com https://.
• Badge vermelho "N falhas consecutivas" - Causa: o endpoint de destino retornou erro nas últimas N entregas (5xx, 4xx, timeout ou conexão recusada). Solução: confira se a URL está acessível em HTTPS, valide os logs em Logs > Webhooks para ver a resposta do servidor e use Testar Webhook após corrigir.
• Webhook ficou desativado sozinho - Causa: atingiu 10 falhas consecutivas e a desativação automática foi acionada. Solução: corrija o destino, regenere o secret se necessário, reative pelo toggle e teste com Testar Webhook.
• Eventos duplicados no destino - Causa: o mesmo evento foi reentregue pelo mecanismo de retry após timeout no seu lado. Solução: dedupe no destino pela chave event_id do payload - ela é estável entre as tentativas.
• HTTP 401 logo após regenerar secret - Causa: o sistema externo ainda valida com o secret antigo. Solução: atualize o secret no destino e reenvie via Testar Webhook.
• Webhook não disparou após uma ação - Causa: a ação aconteceu dentro de uma transação que sofreu rollback, ou o webhook não está inscrito naquele evento, ou está inativo. Solução: confira a lista de eventos do webhook, veja se está ativo e verifique nos logs do sistema se houve rollback da operação.

Onde encontrar

• URL: /admin/configuracoes/api - aba Webhooks
• Caminho no menu: Configurações > API > Webhooks
• Permissão necessária: ver as configurações para visualizar, editar as configurações para criar, editar, regenerar secret, testar, ativar/desativar e excluir
• Módulo necessário: nenhum

Veja também

• Configurações - API e Webhooks
• Integrações e Conectores
• API REST
• Meios de pagamento de Pagamento