webhooks:write para gerenciar assinaturas e webhooks:read para listá-las.
Criando uma assinatura
Crie uma assinatura de webhook comPOST /webhooks:
secret — copie-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:
Semântica de retentativa
Se seu endpoint não retornar uma resposta2xx 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
2xxantes 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-Idpara 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.