Skip to main content
Webhooks permitem que você assine eventos da VMArea e receba notificações HTTP POST em tempo real no seu próprio endpoint HTTPS. Requer o escopo webhooks:write para gerenciar assinaturas e webhooks:read para listá-las.

Criando uma assinatura

Crie uma assinatura de webhook com POST /webhooks:
A resposta inclui um campo secretcopie-o imediatamente, ele é exibido apenas uma vez. Você usará esse segredo para verificar as requisições recebidas. Os URLs de endpoint devem usar HTTPS. Cada conta pode ter até 10 assinaturas de webhook ativas.

Tipos de evento

Verificação de assinatura

Toda entrega inclui uma assinatura HMAC-SHA256 para que você possa confirmar que a requisição veio da VMArea. Cabeçalhos enviados em cada entrega: Exemplo de verificação:
Sempre use crypto.timingSafeEqual (ou equivalente) para evitar ataques de timing.

Semântica de retentativa

Se seu endpoint não retornar uma resposta 2xx em 15 segundos, a VMArea tenta a entrega novamente até 3 tentativas no total com backoff exponencial (atraso inicial de 10 segundos, dobrando a cada tentativa). Após 50 falhas consecutivas de entrega em todos os eventos, a assinatura de webhook é desativada automaticamente. Você pode reativá-la pelo painel ou via PATCH /webhooks/:id com { "isActive": true }. O histórico de entregas (código de status, flag de sucesso, contagem de tentativas) está disponível em GET /webhooks/:id/deliveries.

Boas práticas

  • Responda rapidamente. Retorne 2xx antes de qualquer processamento pesado — delegue o trabalho a uma fila para não atingir o timeout de 15 segundos.
  • Torne os handlers idempotentes. O mesmo evento pode ser entregue mais de uma vez (ex.: após uma retentativa). Use X-VMArea-Delivery-Id para deduplicar.
  • Sempre verifique a assinatura. Não confie no payload sem validar o HMAC.
  • Use um endpoint dedicado por ambiente (produção, staging) para inspecionar e reproduzir eventos de forma independente.