Quatro superfícies
API, webhook, SDK do widget e workflow são distintos
Comece por uma transação: criar contacto CRM, atualizar ticket ou arquivar mensagem. Nomeie emissor, recetor, trigger, campos, latência, erro e registo principal.
Exija URL, versão, autenticação, scopes, endpoints, catálogo de eventos, payloads, paginação, limites, changelog, retirada e suporte para esse caso.
| Superfície | Finalidade | Não inclui automaticamente |
|---|---|---|
| API produto | ler/escrever registos e executar ações | eventos em tempo real ou interface |
| Webhook | notificar endpoint sobre eventos escolhidos | consultas livres, histórico completo ou exactly-once |
| SDK widget | controlar browser, identidade, aspeto ou tracking | API servidor para agentes, export ou compliance |
| Power Platform | orquestrar Teams, conectores e sistemas | API nativa geral ou conector pronto para cada CRM |
Matriz de provas
O que as fontes oficiais demonstram
| Produto | Documentado | Limite antes da compra |
|---|---|---|
| WebChat | palavra-chave, conector Teams, Power Automate e sistemas opcionais | sem API geral, webhook produto ou SDK comprovado publicamente |
| Chatwoot | APIs Application, Client e Platform; webhooks de conta HMAC | testar token, classe API, Cloud/self-hosted e entrega |
| Tidio | OpenAPI, Widget SDK e webhooks assinados com tópico, versão e ID | Plus/Premium owner/admin; alterações OpenAPI sem webhook |
| LiveChat | APIs Agent/Customer, Web/RTM, webhooks e scopes | validar app, OAuth/PAT, funções, filtros, plano e versão |
Operação
At-least-once exige idempotência e reconciliação
Tidio documenta duplicados, ordem não garantida, ID único e ausência de webhook para alterações OpenAPI. LiveChat indica ack curto e retries limitados. Chatwoot documenta assinatura, tempo e delivery; o PoC deve provar retry e ordem da versão.
HTTP verdes não bastam. Meça recebidos, verificados, deduplicados, processados, falhados e reconciliados com ID de negócio.
- Responda 2xx rapidamente e processe depois em fila assíncrona.
- Valide assinatura no body bruto, timestamp e janela; rode secrets.
- Deduplicate por delivery/webhook/event ID e torne efeitos retry-safe.
- Ordene por hora de negócio e ID estável, não só chegada.
- Coloque falhas em quarentena/dead letter, alerte e permita replay controlado.
- Reconcilie por API porque eventos podem atrasar, duplicar, filtrar ou faltar.
- Versione esquema e consumidor; tolere campos novos e bloqueie obrigatórios ausentes.
Segurança e privacidade
Minimizar tokens, payloads e direitos de escrita
Assinatura válida prova origem e integridade sob o secret, não autorização de negócio para agir.
Com Teams/Power Platform inclua owner do flow, conexões, DLP, ambientes, licenças e retorno ao visitante.
- Separe teste/produção, secrets webhook, tokens API e identidades interativas.
- Conceda apenas scopes necessários; acesso global exige justificação.
- Mapeie nome, email, telefone, texto, anexos, browser e notas internas.
- Encripte fila, logs, replay e secrets; mascare dados na telemetria.
- Proteja write-back com estado, allowlist, aprovação e auditoria.
- Defina retenção, acesso e eliminação para eventos, erros, exports e backups.
Aceitação
Oito testes antes de escolher
- 01
Fixar contrato
Caso, registo, versão, endpoints, eventos, campos e latência.
- 02
Negar acesso
Token expirado, errado, insuficiente e conta externa falham.
- 03
Validar assinatura
Body alterado, hora antiga, secret falso e replay não agem.
- 04
Duplicar
Mesmo evento repetido/paralelo tem um efeito funcional.
- 05
Quebrar ordem
Update antes de create, close tardio e mensagens simultâneas.
- 06
Forçar falha
Timeout, 500, fila, alvo e limite com retry, alerta e recovery.
- 07
Reconciliar lacuna
Perder webhook ou usar origem API e recuperar registo.
- 08
Provar saída
Rodar secret, revogar app, remover webhook, exportar delta e eliminar cópias.