​

Webhooks das linhas telefônicas

• Um webhook de número — mesmo um inscrito em "*" — nunca recebe um evento phone_line.*.
• Um webhook de linha recebe apenas eventos phone_line.*, nunca eventos de mensagem ou de número.

​

Configurar (somente pelo painel)

• URL de destino — precisa ser https.
• Eventos — escolha um ou mais dos eventos abaixo, ou todos ("*"). Neste cadastro, "*" significa todos os eventos de linha. É obrigatório escolher pelo menos um.
• Segredo de assinatura — exibido uma única vez, quando o webhook é criado (começa com plwh_). Guarde-o imediatamente: nada o exibe de novo, e não há rotação. Para trocá-lo, crie um novo webhook, passe seu receptor a usar o segredo dele e exclua o antigo.
• Pausar / retomar e excluir. O painel não edita a URL nem os eventos de um webhook: crie um novo webhook e exclua o antigo.
• Log de entregas — por webhook: evento, status (pendente, entregue, com falha), tentativas, o status HTTP que seu endpoint respondeu e o último erro.

​

Eventos

​

Formato do payload

{
  "id": "cmg5k4d1v0003dl8example2m",
  "event": "phone_line.purchased",
  "createdAt": "2026-10-01T14:03:11.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200",
    "currentPeriodEnd": "2026-11-01T14:03:11.000Z"
  }
}

​

Payloads

{
  "id": "cmg5k4d1v0003dl8example2m",
  "event": "phone_line.purchased",
  "createdAt": "2026-10-01T14:03:11.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200",
    "currentPeriodEnd": "2026-11-01T14:03:11.000Z"
  }
}

{
  "id": "cmg5k4d1v0004dl8example3n",
  "event": "phone_line.code_received",
  "createdAt": "2026-10-01T14:11:51.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200",
    "activationId": "cmg5k3a7c0002ac8example4q",
    "code": "123456"
  }
}

{
  "id": "cmg5k4d1v0005dl8example4p",
  "event": "phone_line.renewed",
  "createdAt": "2026-11-01T14:17:05.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200",
    "currentPeriodEnd": "2026-12-01T14:03:11.000Z"
  }
}

{
  "id": "cmg5k4d1v0006dl8example5r",
  "event": "phone_line.payment_failed",
  "createdAt": "2026-11-01T14:17:05.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200"
  }
}

{
  "id": "cmg5k4d1v0007dl8example6s",
  "event": "phone_line.suspended",
  "createdAt": "2026-11-03T14:17:04.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200"
  }
}

{
  "id": "cmg5k4d1v0008dl8example7t",
  "event": "phone_line.returned",
  "createdAt": "2026-11-04T14:17:06.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200"
  }
}

{
  "id": "cmg5k4d1v0009dl8example8u",
  "event": "phone_line.canceled",
  "createdAt": "2026-11-01T14:17:03.000Z",
  "data": {
    "lineId": "cmg5k2l1n0001pl8example9x",
    "number": "551148637200"
  }
}

{
  "id": "cmg5k4d1v0010dl8example9v",
  "event": "phone_line.verification_updated",
  "createdAt": "2026-10-01T13:58:40.000Z",
  "data": {
    "verificationId": "cmg5k0v3r0000vf8example7k",
    "status": "APPROVED"
  }
}

​

Verificar a assinatura

const crypto = require("node:crypto");

// rawBody: the request body exactly as received (Buffer or string).
function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = String(signatureHeader ?? "");
  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
  );
}

import hashlib
import hmac

# raw_body: the request body exactly as received (bytes).
def is_valid_signature(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

​

Entrega e retentativas

• Responda com qualquer 2xx em até 10 segundos. Qualquer outra coisa — outro status, um timeout, um erro de conexão — conta como tentativa com falha.
• 6 tentativas no total: a primeira imediatamente, depois novas tentativas com intervalos de cerca de 30 s, 1 min, 2 min, 4 min e 8 min — normalmente cerca de 15 minutos do início ao fim. Depois da última, a entrega é marcada como falha no log. Uma entrega que não pôde ser enfileirada de início é retomada por uma varredura horária, então a primeira tentativa dela pode vir mais tarde.
• Redirecionamentos não são seguidos. Uma resposta 3xx conta como tentativa com falha.
• Pelo menos uma vez. Se o seu endpoint processou o evento, mas não respondeu a tempo, a retentativa o entrega de novo, com o mesmo id. A ordem não é garantida.
• Webhooks pausados ou excluídos. Um evento é entregue somente aos webhooks que estão ativos e inscritos no momento em que ele acontece. Cada tentativa confere o webhook de novo: uma entrega cujo webhook está pausado quando uma tentativa chega — inclusive uma que já está nas retentativas — é marcada como falha e não é enviada depois; excluir um webhook descarta as entregas pendentes dele. Os eventos nunca são reenviados a um webhook criado ou retomado depois.
• Destinos internos são recusados. Uma URL cujo host resolve para um endereço de rede privada ou interna não é chamada, nem recebe novas tentativas. Uma URL assim é aceita na criação do webhook — nesse momento só o https e os nomes dos eventos são conferidos —, então toda entrega para ela fica registrada como falha. Já uma consulta DNS que falha é diferente: recebe novas tentativas como qualquer outra falha.