Política de entregas

Garantia de entrega

A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez em falha de rede, timeout ou reenvio manual. Seu sistema precisa ser idempotente — use o campo id do evento para descartar duplicatas.

async function processar(evento) {
  // `id` é único por entrega e se repete nas retentativas do MESMO evento
  const novo = await db.eventos.insertIfAbsent(evento.id);
  if (!novo) return; // já processado

  // ...
}

Guarde os ids em armazenamento persistente (Redis, Postgres). Um Set em memória some no restart e a deduplicação vai junto.

Timeout e resposta esperada

A SocialSell aguarda 10 segundos. Passou disso, a entrega conta como falha e entra na fila de retentativa.

Sucesso: qualquer 2xx (200, 201, 202, 204).
Falha: qualquer outro status, timeout ou erro de conexão.
Redirects não são seguidos. Um 3xx conta como falha — um 302 apontando para IP interno seria um caminho de SSRF, então a requisição para ali.

Responda 200 imediatamente e processe em background (BullMQ, Celery, SQS). Processar antes de responder é a causa nº 1 de timeout em integração de webhook.

// ✅ responde primeiro, processa depois
app.post('/webhooks/socialsell', (req, res) => {
  res.status(200).send('OK');
  fila.add('processar-evento', req.body);
});

// ❌ pode estourar os 10 segundos
app.post('/webhooks/socialsell', async (req, res) => {
  await sincronizarComErp(req.body.data);
  res.status(200).send('OK');
});

Retentativas

Cada entrega tem até 5 tentativas, com backoff exponencial de base 60 segundos:

Tentativa	Espera desde a falha anterior	Tempo acumulado
1ª	imediata	0
2ª	~1 minuto	~1 min
3ª	~2 minutos	~3 min
4ª	~4 minutos	~7 min
5ª	~8 minutos	~15 min

Depois da 5ª, a entrega é marcada como failed e conta uma falha para a assinatura.

A janela total de recuperação automática é de cerca de 15 minutos. Se o seu endpoint fica fora por mais tempo que isso, use o reenvio manual depois de restabelecer o serviço — o log guarda as entregas dos últimos 15 dias.

Cadência por organização

Para que um volume grande de uma organização não atrase as entregas das outras, cada organização tem uma cadência própria: 100 entregas por minuto. O que passa disso não é descartado — ganha um atraso e sai em seguida, na ordem. Uma importação de 5.000 contatos, por exemplo, é entregue ao longo de cerca de 50 minutos, e nesse meio-tempo os webhooks de outras organizações seguem saindo normalmente.

Reenvio manual e evento de teste não entram nessa cadência: são ações pontuais e saem na hora.

Pausa automática

Depois de 10 falhas consecutivas (10 entregas que esgotaram as 5 tentativas), a assinatura é pausada automaticamente e a organização recebe uma notificação no painel. Uma entrega bem-sucedida zera o contador. A assinatura também é pausada se o plano da organização deixar de incluir o módulo Webhooks ou tiver o limite de endpoints reduzido a zero. Para reativar, corrija o endpoint e mande:

curl -X PATCH https://api.socialsell.ai/v1/webhooks/664f1a2b3c4d5e6f78901234 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Reativar zera o contador de falhas.

Acompanhando a saúde

O objeto da assinatura traz o estado atual:

{
  "id": "664f1a2b3c4d5e6f78901234",
  "name": "Integração ERP",
  "url": "https://meusistema.com/webhooks/socialsell",
  "events": ["deal.won", "channel.disconnected"],
  "status": "active",
  "last_delivery_at": "2026-08-20T14:30:00.000Z",
  "last_failure_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-07-01T10:00:00.000Z",
  "updated_at": "2026-08-20T14:30:00.000Z"
}

Campo	Descrição
`status`	`active` ou `paused`
`consecutive_failures`	Falhas seguidas sem nenhum sucesso. Chegou a 10, pausa.
`last_delivery_at`	Última entrega bem-sucedida
`last_failure_at`	Última falha final

Log de entregas

Toda entrega fica registrada por 15 dias, com o payload enviado e cada tentativa:

curl https://api.socialsell.ai/v1/webhooks/664f1a2b3c4d5e6f78901234/deliveries?limit=50 \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "664e1a2b3c4d5e6f78901299",
      "event_id": "evt_9f2c1a7b4e8d0c3a5b6f7e81",
      "event_type": "deal.won",
      "status": "failed",
      "url": "https://meusistema.com/webhooks/socialsell",
      "attempts": [
        { "at": "2026-08-20T14:30:00.000Z", "status_code": 502, "error": "HTTP 502", "duration_ms": 431 },
        { "at": "2026-08-20T14:31:02.000Z", "status_code": null, "error": "Timeout após 10s", "duration_ms": 10004 }
      ],
      "attempts_count": 2,
      "last_attempt_at": "2026-08-20T14:31:02.000Z",
      "redelivery_of": null,
      "created_at": "2026-08-20T14:30:00.000Z"
    }
  ]
}

O log guarda o payload completo, que inclui dados pessoais do contato. Ele é apagado automaticamente após 15 dias.

Reenvio manual

Qualquer entrega do log pode ser reenviada. O reenvio cria um novo ciclo — com as 5 tentativas — usando o payload original, e aponta para a entrega de origem em redelivery_of:

curl -X POST https://api.socialsell.ai/v1/webhooks/deliveries/664e1a2b3c4d5e6f78901299/redeliver \
  -H "Authorization: Bearer sk_live_..."

O id do evento é preservado — do seu lado, a deduplicação por id continua funcionando e um reenvio não vira registro duplicado.

Reenvio exige assinatura ativa. Endpoint pausado devolve 409 WEBHOOK_PAUSED.

Ordem de entrega

Eventos são despachados na ordem em que acontecem, mas a ordem de chegada não é garantida — retentativas e concorrência entre entregas reordenam. Não assuma sequência: use o created_at do evento para reconstruir a linha do tempo e descarte atualizações mais velhas que o estado que você já tem.

Testando durante o desenvolvimento

A URL precisa ser HTTPS pública. Para receber localmente, exponha sua máquina com um túnel:

ngrok http 3000

Use a URL gerada como endpoint da assinatura. Para conferir a validação sem escrever código, o endpoint POST /v1/webhooks/{id}/test dispara uma entrega assinada de verdade e devolve na hora o status HTTP e a duração do seu endpoint.

Visão geral

Eventos

Gerenciar assinaturas

Garantia de entrega

Timeout e resposta esperada

Retentativas

Cadência por organização

Pausa automática

Acompanhando a saúde

Log de entregas

Reenvio manual

Ordem de entrega

Testando durante o desenvolvimento

​Garantia de entrega

​Timeout e resposta esperada

​Retentativas

​Cadência por organização

​Pausa automática

​Acompanhando a saúde

​Log de entregas

​Reenvio manual

​Ordem de entrega

​Testando durante o desenvolvimento

Garantia de entrega

Timeout e resposta esperada

Retentativas

Cadência por organização

Pausa automática

Acompanhando a saúde

Log de entregas

Reenvio manual

Ordem de entrega

Testando durante o desenvolvimento