Webhooks
Aprenda como integrar notificações em tempo real na sua aplicação
O que são webhooks?
Webhooks são mensagens automáticas enviadas de aplicações quando algo acontece. Eles têm uma mensagem—ou payload—e são enviados para uma URL única (seu endpoint).
Em vez de verificar constantemente nossa API por novos dados (polling), webhooks enviam dados para sua aplicação em tempo real quando eventos ocorrem. Isso é mais eficiente e fornece notificações instantâneas.
Quando um usuário envia uma pesquisa ou formulário no seu site, o Ask Users pode notificar instantaneamente sua aplicação via webhook, permitindo que você:
- Sincronize automaticamente dados com seu CRM (Salesforce, HubSpot, etc.)
- Envie notificações para sua equipe via Slack ou email
- Dispare fluxos de trabalho personalizados em sua aplicação
- Atualize seu banco de dados em tempo real
- Alimente dados em plataformas de análise
Como webhooks funcionam
Evento ocorre
Um usuário envia uma pesquisa ou formulário no seu site. O Ask Users captura este evento e se prepara para notificar sua aplicação.
Webhook disparado
O Ask Users verifica quais webhooks estão configurados para este evento. Se seu webhook está configurado para receber este tipo de evento, preparamos o payload com todos os dados relevantes.
Requisição HTTP POST enviada
Enviamos uma requisição HTTP POST para sua URL de webhook com os dados do evento em formato JSON. A requisição inclui cabeçalhos de segurança (assinatura HMAC) para verificar autenticidade.
Seu endpoint processa os dados
Sua aplicação recebe o webhook, verifica a assinatura e processa os dados. Você pode armazená-los no seu banco de dados, disparar notificações, atualizar registros ou executar qualquer lógica personalizada.
Resposta e retry
Seu endpoint deve responder com um código de status 2xx (tipicamente 200 OK) em até 30 segundos. Se não recebermos uma resposta bem-sucedida, tentaremos automaticamente reenviar a entrega até 5 vezes com backoff exponencial:
- Tentativa 1: Imediata
- Tentativa 2: 1 minuto depois
- Tentativa 3: 5 minutos depois
- Tentativa 4: 15 minutos depois
- Tentativa 5: 1 hora depois
- Tentativa 6: 6 horas depois
Principais recursos
Entrega segura
Todos os webhooks são assinados com assinaturas HMAC-SHA256 para verificar autenticidade
Tentativas automáticas
Entregas que falham são automaticamente tentadas novamente até 5 vezes com backoff exponencial
Entrega em tempo real
Webhooks disparam imediatamente quando eventos ocorrem, tipicamente em milissegundos
Deduplicação de eventos
IDs de eventos únicos previnem processamento duplicado mesmo durante tentativas
Eventos suportados
survey.response.created
Disparado quando uma nova resposta de pesquisa é enviada. Contém os dados completos da resposta, incluindo todas as respostas, informações do respondente e metadados da pesquisa.
form.submission.created
Disparado quando um novo envio de formulário é criado. Inclui todos os dados dos campos do formulário, status de envio e detalhes de configuração do formulário.
Início rápido
Configure webhook no painel
1. Vá para seu painel
2. Navegue para Configurações → Webhooks
3. Clique em Criar Webhook
4. Digite a URL do seu endpoint e selecione os tipos de evento
5. Salve e copie sua chave secreta
Teste seu webhook
Envie uma pesquisa ou formulário de teste para disparar seu webhook e verificar se está funcionando corretamente. Verifique os logs de entrega no seu painel para ver a requisição e resposta.
Implementação de referência de webhook
Aqui está um exemplo completo de como criar e verificar um endpoint de webhook em sua aplicação:
// Node.js/Express example
const crypto = require('crypto');
app.post('/webhooks/askusers', (req, res) => {
const signature = req.headers['x-webhook-signature'];
// Verify signature (see security section)
if (!verifySignature(req.body, signature)) {
return res.status(401).send('Invalid signature');
}
// Process webhook
const { event_type, data } = req.body;
// Return 200 OK immediately
res.status(200).send('OK');
// Process async
processWebhookAsync(event_type, data);
});Exemplo de payload de webhook
Aqui está um exemplo de como um payload de webhook se parece:
{
"event_type": "survey.response.created",
"event_id": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2025-01-15T10:30:00.000Z",
"data": {
"response": {
"id": "response-uuid",
"survey_id": "survey-uuid",
"response_data": {
"question-id-1": "Answer 1",
"question-id-2": "Answer 2"
},
"completion_status": "completed",
"created_at": "2025-01-15T10:30:00.000Z"
},
"survey": {
"id": "survey-uuid",
"title": "Product Feedback Survey"
}
}
}Segurança e verificação
Sempre verifique assinaturas de webhook para garantir que as requisições vieram do Ask Users. Cada webhook inclui um cabeçalho X-Webhook-Signature com uma assinatura HMAC-SHA256.
Exemplo de verificação (Node.js)
const crypto = require('crypto');
function verifySignature(payload, signature) {
const secret = process.env.ASKUSERS_WEBHOOK_SECRET;
const payloadString = JSON.stringify(payload);
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payloadString)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}Exemplo de verificação (Python)
import hmac
import hashlib
import os
def verify_signature(payload: str, signature: str) -> bool:
secret = os.environ['ASKUSERS_WEBHOOK_SECRET']
expected_signature = hmac.new(
secret.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected_signature)Melhores práticas
1. Responda rapidamente
Sempre retorne 200 OK imediatamente, então processe o webhook de forma assíncrona. Mantenha o tempo de resposta abaixo de 30 segundos para evitar timeouts.
2. Lide com entregas duplicadas
Use o event_id para deduplicar eventos. Armazene IDs de eventos processados para prevenir processamento duplicado. Isso é importante porque tentativas podem causar a entrega do mesmo evento múltiplas vezes.
3. Use HTTPS
Sempre use URLs HTTPS para endpoints de webhook em produção para garantir segurança de dados e prevenir ataques man-in-the-middle.
4. Monitore logs de entrega
Verifique seus logs de entrega de webhook no painel para monitorar taxas de sucesso e identificar problemas. Os logs mostram a requisição/resposta completa para troubleshooting.
5. Implemente tratamento adequado de erros
Envolva sua lógica de processamento de webhook em blocos try-catch e registre erros. Retorne códigos de status HTTP apropriados: 200-299 para sucesso, 4xx para erros do cliente (que não serão tentados novamente), 5xx para erros do servidor (que dispararão tentativas).
Integração sem código
Não quer escrever código? Use webhooks com Zapier ou Make:
- Crie um novo trigger "Catch Webhook" no Zapier ou Make
- Copie a URL do webhook fornecida
- Crie um webhook no Ask Users com essa URL
- Teste enviando um formulário ou pesquisa
- Construa seu fluxo de trabalho de automação!
Precisa de ajuda?
Se você tem dúvidas ou precisa de assistência com webhooks:
- • Verifique os logs de entrega no seu painel
- • Revise a seção de troubleshooting acima
- • Entre em contato conosco em support@askusers.org