Webhooks

Webhooks permitem que sua equipe receba notificações automáticas em tempo real no seu próprio servidor quando eventos acontecem no Pliic, como uma nova sugestão enviada ou uma mudança de status em um ticket.

Webhooks estão disponíveis nos planos Starter (até 3 endpoints) e Pro (ilimitados). O plano Gratuito não inclui este recurso. Apenas membros com papel Administrador ou Dono podem gerenciar webhooks.

Criando um endpoint

1. Acesse Configurações → Webhooks
2. Clique em Adicionar endpoint
3. Preencha os campos:
   • Nome: identificação interna do endpoint
   • URL: endereço HTTPS público que receberá as notificações
   • Eventos: selecione quais eventos devem disparar este endpoint
4. Clique em Criar

Ao criar, um segredo de assinatura (whsec_…) é exibido uma única vez. Copie e armazene com segurança, ele não pode ser recuperado depois.

Eventos disponíveis

Evento	Descrição
suggestion.created	Uma nova sugestão foi enviada.
suggestion.status_changed	O status de uma sugestão foi alterado.
suggestion.commented	Um comentário foi adicionado a uma sugestão.
ticket.created	Um novo ticket foi aberto.
ticket.status_changed	O status de um ticket foi alterado.
ticket.replied	Uma resposta foi adicionada a um ticket.

Formato do payload

Cada entrega é uma requisição POST com Content-Type: application/json e o seguinte formato:

{
  "id": "018e1234-5678-7abc-def0-123456789abc",
  "event": "suggestion.created",
  "created_at": "2024-01-15T14:30:00Z",
  "data": { ... }
}

Campo	Tipo	Descrição
id	string (UUID)	Identificador único da entrega.
event	string	Nome do evento disparado.
created_at	string (ISO 8601)	Data e hora do evento em UTC.
data	object	Dados específicos do evento.

Cabeçalhos da requisição

Cada entrega inclui os seguintes cabeçalhos HTTP:

Cabeçalho	Descrição
X-Pliic-Signature	Assinatura HMAC-SHA256 do corpo bruto da requisição.
X-Pliic-Event	Nome do evento (ex: suggestion.created).
X-Pliic-Delivery	UUID único desta entrega.

Verificando a assinatura

Verificar a assinatura garante que a requisição foi enviada pelo Pliic e que o conteúdo não foi alterado no caminho.

Calcule HMAC-SHA256(segredo, corpo_bruto) e compare com o valor do cabeçalho X-Pliic-Signature usando comparação em tempo constante.

PHP:

function verificarAssinatura(string $segredo, string $corpoRaw, string $assinatura): bool
{
    $esperado = hash_hmac('sha256', $corpoRaw, $segredo);

    return hash_equals($esperado, $assinatura);
}

Node.js:

const crypto = require('crypto');

function verificarAssinatura(segredo, corpoRaw, assinatura) {
  const esperado = crypto
    .createHmac('sha256', segredo)
    .update(corpoRaw)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(esperado),
    Buffer.from(assinatura),
  );
}

Cuidado

Sempre use o corpo bruto (raw body) da requisição ao calcular a assinatura, nunca o objeto JSON já parseado. Parsear e re-serializar o JSON pode alterar a ordem dos campos e invalidar a verificação.

Entregas e reenvios

Se o seu servidor retornar um status diferente de 2xx ou a conexão expirar, o Pliic tentará reenviar automaticamente com backoff exponencial:

Tentativa	Atraso aproximado
1ª (reenvio)	5 minutos
2ª	15 minutos
3ª	45 minutos
4ª	135 minutos
5ª	405 minutos (~6,75 horas)

Após 5 tentativas sem sucesso, a entrega é abandonada.

O histórico completo de cada entrega (status, código de resposta e número de tentativas) está disponível na página de detalhes do endpoint.

Testando o endpoint

Na página de detalhes do endpoint, clique em Enviar teste. O Pliic enviará um evento webhook.ping para que você possa verificar se o servidor está recebendo requisições corretamente antes de ativar eventos reais.

Segurança

• Apenas URLs HTTPS públicas são aceitas. Endereços internos, de rede privada ou localhost são rejeitados.
• O certificado TLS do servidor de destino é sempre verificado.
• Nunca compartilhe o segredo de assinatura nem o inclua em código público ou logs.