Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt

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

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: 
curl -X POST https://api.vmarea.com/api/public/v1/webhooks \
  -H "x-api-key: $VMAREA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example.com/hooks/vmarea",
    "events": ["vm.created", "vm.started", "billing.payment_received"],
    "description": "Production listener"
  }'
A resposta inclui um campo 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

EventoDescrição
vm.createdUma VM concluiu o provisionamento.
vm.startedUma VM foi iniciada.
vm.stoppedUma VM foi parada.
vm.restartedUma VM foi reiniciada.
vm.suspendedUma VM foi suspensa (ex.: por inadimplência).
vm.terminatedUma VM foi excluída permanentemente.
vm.renewedO ciclo de faturamento de uma VM foi renovado.
billing.payment_receivedUma recarga da carteira foi processada com sucesso.
billing.low_balanceO saldo da carteira caiu abaixo do mínimo necessário para cobrir as próximas renovações.
ticket.replyUm ticket de suporte recebeu uma nova resposta.

​
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:
CabeçalhoValor
X-VMArea-EventO tipo de evento (ex.: vm.started).
X-VMArea-Signaturesha256=<hex-digest> do corpo JSON bruto, assinado com o segredo do seu webhook.
X-VMArea-Delivery-IdUm ID único para esta tentativa de entrega.
Exemplo de verificação: 
import crypto from "node:crypto";

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Exemplo com Express
app.post("/hooks/vmarea", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-vmarea-signature"];
  if (!verifySignature(req.body, sig, process.env.VMAREA_WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }
  const event = req.headers["x-vmarea-event"];
  const payload = JSON.parse(req.body);
  // trate o evento ...
  res.status(200).send("ok");
});
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.