Conecte o PesQuiza aos sistemas da sua empresa

Visão geral

O PesQuiza conversa com outros sistemas de duas formas:

Os dois ficam em Configurações › Integrações e estão disponíveis nos planos que incluem integrações (veja a página de preços). Só o proprietário e os administradores da organização gerenciam integrações.

Slack: alertas num canal

Ideal para avisar o time de Customer Success ou de RH quando alguém dá uma nota baixa. Você precisa ser administrador do Slack ou pedir a quem é.

1. 1No Slack, acesse api.slack.com/apps e clique em Create New App › From scratch. Dê um nome (ex.: "PesQuiza") e escolha o workspace.
2. 2No menu do app, abra Incoming Webhooks e ative a opção Activate Incoming Webhooks.
3. 3Clique em Add New Webhook to Workspace, escolha o canal (ex.: #cs-alertas) e autorize.
4. 4Copie a Webhook URL, que começa com https://hooks.slack.com/services/….
5. 5No PesQuiza, em Configurações › Integrações, clique em Novo webhook, escolha o tipo Slack, cole a URL e marque os eventos (ex.: Nota baixa (detrator)).
6. 6Salve e use o botão Testar: uma mensagem de exemplo aparece no canal.

A mensagem traz a pesquisa, a nota, o comentário e, em pesquisas identificadas, quem respondeu. Por exemplo: Nota baixa em "NPS relacional" (Rita Alves · [email protected]): NPS 3 — "O suporte demorou."

Microsoft Teams: cartões numa conversa

O Teams recebe webhooks pelo aplicativo Workflows (Power Automate).

1. 1No canal do Teams, abra o menu … do canal e escolha Workflows.
2. 2Procure o modelo "Postar em um canal quando uma solicitação de webhook for recebida" (Post to a channel when a webhook request is received).
3. 3Dê um nome ao fluxo, confirme a equipe e o canal e conclua. O Teams mostra a URL do webhook: copie.
4. 4No PesQuiza, crie o webhook do tipo Microsoft Teams, cole a URL, marque os eventos, salve e clique em Testar.

Webhook para o seu sistema

Para CRM, ERP, BI ou um sistema próprio. O PesQuiza envia um POST com um JSON para o endereço que você cadastrar, no tipo Meu sistema. Ao criar o webhook, o PesQuiza mostra um segredo de assinatura uma única vez: guarde-o, ele serve para conferir que a mensagem veio mesmo do PesQuiza.

Eventos

Cabeçalhos

Exemplo: resposta concluída (pesquisa identificada)

{
  "id": "01926f3a-7c1e-7b2a-9d4f-3e8a2b1c0d9e",
  "event": "response.completed",
  "created_at": "2026-09-29T11:40:12-03:00",
  "organization": { "id": "9d2c…", "name": "Atlas Serviços" },
  "data": {
    "survey": { "id": "01a0e8…", "title": "NPS relacional · 3º trimestre" },
    "response": {
      "id": "01a0f1…",
      "completed_at": "2026-09-29T11:40:10-03:00",
      "channel": "email",
      "duration_seconds": 94
    },
    "contact": {
      "name": "Rita Alves",
      "email": "[email protected]",
      "fields": { "empresa": "Nexa Saúde", "segmento": "Serviços" }
    },
    "hidden_fields": { "pedido": "A-1042" },
    "answers": [
      { "key": "q1", "question": "De 0 a 10, qual a probabilidade de nos recomendar?", "type": "nps", "value": 9, "comment": null },
      { "key": "q2", "question": "O que mais pesou na sua nota?", "type": "long_text", "value": "Atendimento rápido.", "comment": null }
    ]
  }
}

answers traz uma linha por pergunta: value é número nas notas (NPS, escala, estrelas, número), texto nas demais e um objeto item → resposta nas matrizes. hidden_fields são os campos ocultos passados no link ou no widget.

Exemplo: nota baixa

{
  "id": "01926f3b-…",
  "event": "detractor.alert",
  "created_at": "2026-09-29T11:40:12-03:00",
  "organization": { "id": "9d2c…", "name": "Atlas Serviços" },
  "data": {
    "survey": { "id": "01a0e8…", "title": "NPS relacional · 3º trimestre" },
    "respondent": "Rita Alves · [email protected]",
    "scores": [
      { "question": "De 0 a 10, qual a probabilidade de nos recomendar?", "metric": "NPS", "score": "3", "comment": "O suporte demorou." }
    ]
  }
}

Entrega, novas tentativas e desativação

• Responda com um status 2xx em até 10 segundos. Se precisar de processamento demorado, guarde o evento e processe depois.
• Se o destino falhar ou demorar, o PesQuiza tenta de novo até 5 vezes: após 30 segundos, 2 minutos, 10 minutos e 30 minutos. Por isso, trate eventos repetidos pelo X-PesQuiza-Delivery.
• Depois de 20 falhas seguidas, o webhook é desativado. Corrija o endereço e reative-o em Configurações › Integrações.
• Só são aceitos endereços https:// públicos. Redirecionamentos não são seguidos.
• A ordem de chegada não é garantida: use created_at quando a ordem importar.

Conferir a assinatura

Calcule o HMAC-SHA256 do corpo exatamente como chegou (antes de converter o JSON), com o segredo do webhook, e compare com o cabeçalho X-PesQuiza-Signature usando uma comparação de tempo constante. Se não bater, recuse com 401.

PHP

$body = file_get_contents('php://input');
$expected = 'sha256='.hash_hmac('sha256', $body, getenv('PESQUIZA_WEBHOOK_SECRET'));

if (! hash_equals($expected, $_SERVER['HTTP_X_PESQUIZA_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// ... processe $event['data'] e responda rápido:
http_response_code(200);

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Use o corpo cru: a assinatura é calculada sobre os bytes recebidos.
app.post('/webhooks/pesquiza', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.PESQUIZA_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const received = req.get('X-PesQuiza-Signature') || '';

  if (expected.length !== received.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);
  // ... processe event.data
  res.sendStatus(200);
});

Python (Flask)

import hashlib, hmac, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/pesquiza")
def pesquiza():
    body = request.get_data()  # corpo cru
    expected = "sha256=" + hmac.new(
        os.environ["PESQUIZA_WEBHOOK_SECRET"].encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, request.headers.get("X-PesQuiza-Signature", "")):
        abort(401)

    event = request.get_json()
    # ... processe event["data"]
    return "", 200

Zapier, Make e n8n (sem programar)

Plataformas de automação recebem o webhook e levam os dados para planilhas, CRMs e outras ferramentas.

1. 1Crie um cenário (Make), zap (Zapier) ou fluxo (n8n) que comece com um gatilho de webhook personalizado (Custom webhook, Catch Hook ou Webhook). A plataforma gera uma URL.
2. 2No PesQuiza, crie um webhook do tipo Meu sistema com essa URL e clique em Testar: a plataforma de automação reconhece os campos do evento.
3. 3Monte os passos seguintes com os campos recebidos.

API REST

Crie uma chave em Configurações › Integrações (Nova chave). Ela aparece uma única vez e dá acesso aos dados da organização: guarde-a num cofre de senhas e nunca a coloque no código do navegador.

Endpoints

Exemplo: pesquisa após o atendimento

Quando um chamado é encerrado no seu sistema, convide o cliente para a pesquisa de CSAT com 2 horas de atraso:

curl -X POST https://pesquiza.com.br/api/v1/surveys/01a0e8…/invitations \
  -H "Authorization: Bearer pqz_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "[email protected]",
        "name": "Rita Alves",
        "fields": { "chamado": "48213", "atendente": "Carlos" },
        "delay_minutes": 120
      }'

Os fields ficam no contato: podem aparecer no texto da pesquisa ({{contato.atendente}}) e servem de filtro na apuração.

Privacidade

As integrações seguem o nível de identificação de cada pesquisa:

Os dados enviados aos destinos cadastrados passam a ser tratados pela sua organização. Envie a cada sistema só o necessário.