Skip to main content

​
Garantias de entrega

A SocialSell garante entrega at-least-once — o mesmo evento pode ser entregue mais de uma vez em situações de falha de rede ou timeout. Seu sistema deve ser idempotente: use o campo id do evento para descartar duplicatas. 
const processedEvents = new Set();

function handleEvent(event) {
  if (processedEvents.has(event.id)) {
    console.log('Evento duplicado ignorado:', event.id);
    return;
  }

  processedEvents.add(event.id);
  // processar...
}
Em produção, armazene os IDs processados em um banco de dados persistente (Redis, PostgreSQL, etc.) — um Set em memória é perdido ao reiniciar a aplicação.

​
Timeout e resposta esperada

A SocialSell aguarda 10 segundos pela resposta do seu endpoint. Se não receber resposta em tempo hábil, considera a entrega como falha e agenda uma retentativa. Resposta esperada: qualquer status 2xx (200, 201, 202, 204). Resposta de falha: qualquer outro status HTTP, timeout ou erro de conexão.
Responda com 200 OK o mais rápido possível e processe o evento de forma assíncrona (em uma fila como BullMQ, Celery, RabbitMQ). Isso evita timeouts causados por processamento lento ou chamadas a APIs externas dentro do handler.
// ✅ Correto: responde imediatamente, processa depois
app.post('/webhooks/socialsell', (req, res) => {
  res.status(200).send('OK'); // responde imediatamente
  queue.add('process-event', req.body); // processa em background
});

// ❌ Evitar: processa antes de responder (risco de timeout)
app.post('/webhooks/socialsell', async (req, res) => {
  await syncContactToERP(req.body.data); // pode demorar > 10s
  res.status(200).send('OK');
});

​
Política de retentativas

Quando uma entrega falha, a SocialSell tenta novamente com backoff exponencial:
TentativaAguarda
1ªImediato
2ª5 minutos
3ª30 minutos
4ª2 horas
5ª8 horas
Após 5 falhas consecutivas, a assinatura é automaticamente pausada (status: paused) para proteger o seu sistema de requisições desnecessárias.

​
Monitorando falhas

O objeto da assinatura inclui um contador de falhas: 
{
  "id": "664f1a2b...",
  "status": "active",
  "consecutive_failures": 2,
  "last_failure_at": "2026-06-10T14:00:00.000Z",
  "last_failure_reason": "Connection timeout"
}
CampoDescrição
consecutive_failuresFalhas consecutivas sem sucesso
last_failure_atTimestamp da última falha
last_failure_reasonMotivo da falha (timeout, status HTTP, etc.)

​
Reativando uma assinatura pausada

Após corrigir o problema no seu endpoint, reative a assinatura: 
curl -X PATCH https://api.socialsell.ai/v1/webhooks/664f1a2b... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

​
Ordem de entrega

Eventos são entregues na ordem em que ocorrem, mas a ordem de entrega não é garantida em caso de retentativas. Por exemplo, se contact.updated falhou e está sendo retentado, contact.updated mais recente pode ser entregue antes da retentativa. Projete seu sistema para lidar com eventos fora de ordem usando os campos created_at do evento.

​
Ambientes e testes

Durante desenvolvimento, use ferramentas como ngrok, localtunnel ou webhook.site para receber eventos localmente: 
# ngrok expõe localhost:3000 publicamente
ngrok http 3000
# Use a URL gerada como endpoint da assinatura
Para testar sem um endpoint público, use o endpoint /v1/webhooks/:id/test (disponível no painel) para disparar um evento de exemplo com o payload real.