Webhooks

​

Por que usar Webhooks?

• Automação de Fluxo: Envie alertas para o Slack ou Discord quando receber um feedback negativo.
• Sincronização de CRM ou automação: Atualize o cadastro do cliente no Salesforce ou HubSpot com a nota do NPS.
• E-mail de Follow-up: Dispare um e-mail automático de agradecimento ou suporte logo após o envio.

​

Configurando um Webhook

​

Estrutura do Payload (JSON)

{
  "event": "response.created",
  "created_at": "2026-01-20T23:56:00Z",
  "data": {
    "id": "res_12345",
    "survey_id": "cmjt5c5d00003jr0wngf8kjga",
    "sentiment": "POSITIVE",
    "sentiment_score": 92,
    "answers": [
      {
        "questionId": "q_01",
        "label": "Qual sua nota para o nosso serviço?",
        "value": "10"
      },
      {
        "questionId": "q_02",
        "label": "O que podemos melhorar?",
        "value": "O atendimento foi excelente!"
      }
    ],
    "metadata": {
      "user_id": "99",
      "plan": "pro"
    }
  }
}

​

Segurança e Verificação

X-Opiny-Signature: sha256=hash_gerado

​

Validando a Assinatura

const crypto = require('crypto');

const secret = 'sua_chave_secreta_webhook';
const signature = req.headers['x-opiny-signature'];
const payload = JSON.stringify(req.body);

const expectedSignature = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (`sha256=${expectedSignature}` === signature) {
  // Requisição legítima
}

​

Melhores Práticas

• Status 200 OK: Seu servidor deve responder com um status HTTP 200 ou 204 rapidamente. Se a resposta demorar mais de 10 segundos, consideraremos como falha.
• Entrega: atualmente o envio é feito uma vez, com timeout de 10 segundos. Retorne 200 ou 204 e use o identificador do evento para manter o processamento idempotente.
• Idempotência: Como webhooks podem ser reenviados em caso de falha na rede, certifique-se de que seu sistema consegue lidar com o recebimento do mesmo id de resposta mais de uma vez.