Em quase toda conversa sobre automação de atendimento, alguém fala que “é só puxar pela API” ou que “o sistema avisa por webhook”. Para quem cuida de vendas, financeiro ou atendimento, essas frases costumam encerrar a discussão em vez de esclarecê-la. Não precisa ser assim. Os dois conceitos são simples, e entendê-los ajuda a fazer perguntas melhores, estimar prazos com mais realismo e perceber quando uma proposta técnica tem lacunas.

O que é uma API

API é a sigla em inglês para interface de programação de aplicações. Traduzindo para o dia a dia: é a porta de entrada que um sistema oferece para que outros sistemas façam pedidos a ele, seguindo regras combinadas.

Pense no balcão de uma distribuidora que atende só por pedido escrito. O cliente não entra no estoque nem mexe nas prateleiras. Ele entrega um formulário com campos definidos e recebe de volta uma confirmação ou uma recusa com o motivo. A API funciona do mesmo jeito: o outro sistema não acessa o banco de dados diretamente, apenas envia pedidos no formato aceito e recebe respostas padronizadas.

Endpoint: o endereço de cada serviço

Uma API costuma oferecer vários serviços: consultar um cliente, criar um pedido, cancelar uma cobrança. Cada um fica em um endereço próprio, parecido com o endereço de um site, chamado endpoint. Um sistema de pedidos, por exemplo, poderia ter um endpoint terminado em /pedidos para listar pedidos e outro terminado em /pedidos/1234 para consultar o pedido número 1234.

Requisição e resposta

Toda conversa com uma API tem duas partes. A requisição é o pedido: qual endpoint, qual ação e quais dados. A resposta é o retorno: os dados pedidos ou uma mensagem de erro. As ações mais comuns têm nomes padronizados:

  • GET: consultar algo, sem alterar nada (ver o status de um pedido).
  • POST: criar algo novo (registrar um lead, enviar uma mensagem).
  • PUT ou PATCH: alterar algo que já existe (atualizar o telefone de um cliente).
  • DELETE: remover algo (cancelar um agendamento).

A resposta normalmente vem em um formato de texto chamado JSON, que organiza as informações em pares de nome e valor. Uma consulta de pedido poderia devolver algo assim (exemplo ilustrativo):

{
  "pedido": "1234",
  "status": "pago",
  "valor": 189.90,
  "cliente": "Maria S."
}

Junto com os dados vem um código numérico que resume o resultado. Vale conhecer três famílias: códigos que começam com 2 indicam sucesso (o famoso 200); os que começam com 4 indicam que o pedido estava errado ou não era permitido (404 é “não encontrado”, 401 é “não autenticado”, 403 é “sem permissão” e 429 é “pedidos demais em pouco tempo”); e os que começam com 5 indicam falha do lado de quem respondeu. Isso já indica de que lado está o problema.

Autenticação e tokens

Nenhuma API séria responde a qualquer um. Antes de atender um pedido, ela verifica quem está pedindo e o que essa pessoa pode fazer. Esse processo se chama autenticação, e a forma mais comum é o uso de um token ou chave de API: uma sequência longa de letras e números enviada junto com cada requisição.

A comparação mais útil é com um crachá de acesso. O crachá identifica quem entra, define em quais salas pode entrar e pode ser desativado a qualquer momento. Com tokens é igual:

  • Identidade: o token diz qual sistema ou usuário está fazendo o pedido.
  • Permissões (escopos): um token pode servir só para leitura, outro para leitura e escrita. Um bom projeto pede apenas as permissões necessárias.
  • Validade: alguns tokens expiram em horas ou dias e precisam ser renovados; outros são de longa duração e exigem ainda mais cuidado.
  • Revogação: se vazar, o token deve ser cancelado e substituído, como um crachá perdido. Quem tem o token tem o acesso, então ele nunca deve circular por e-mail ou grupo de mensagens.

Na plataforma do WhatsApp Business, por exemplo, a Meta indica que empresas que fazem a própria integração usem tokens de usuário do sistema, criados no gerenciador de negócios da conta empresarial, em vez de tokens ligados ao perfil pessoal de um desenvolvedor. Os tokens de usuário comum expiram em poucas horas e servem basicamente para testes; os de usuário do sistema foram pensados para serviços automatizados e não dependem de uma pessoa específica continuar na empresa. A documentação da Meta sobre tokens de acesso descreve esses tipos.

O que é um webhook

A API responde quando alguém pergunta. O webhook faz o caminho inverso: é o sistema que avisa outro sistema quando algo acontece, sem esperar ser perguntado.

Funciona assim. O sistema que vai receber os avisos cria um endereço próprio, uma URL, e cadastra esse endereço no sistema de origem, escolhendo quais eventos quer acompanhar: “pagamento aprovado”, “mensagem recebida”, “pedido enviado”. A partir daí, sempre que um desses eventos ocorre, o sistema de origem envia automaticamente uma requisição para aquela URL com os detalhes do que aconteceu.

É como pedir à transportadora que mande um SMS quando a encomenda sair para entrega, em vez de abrir o site de rastreio a cada hora. O aviso chega no momento certo e ninguém precisa ficar conferindo.

A API oficial do WhatsApp depende bastante desse mecanismo. Quando um cliente manda mensagem para a empresa, ou quando uma mensagem enviada é entregue ou lida, a Meta comunica o evento por webhook ao sistema de atendimento conectado. Se ainda há dúvida entre usar o aplicativo ou a API, o comparativo WhatsApp Business App ou API oficial ajuda a decidir.

Consultar ou ser avisado: a diferença na prática

Um sistema pode saber que algo mudou em outro de duas formas. A primeira é perguntar de tempos em tempos, técnica conhecida como polling: a cada cinco minutos, o sistema consulta a API e pergunta se há pedidos novos. A segunda é receber o aviso por webhook no instante em que a mudança acontece. Nenhuma é sempre melhor; cada uma tem seu lugar.

Aspecto Consultar (API com polling) Ser avisado (webhook)
Quem inicia O sistema interessado pergunta O sistema de origem avisa
Tempo até saber da mudança Depende do intervalo entre consultas Quase imediato
Volume de requisições Muitas consultas sem novidade Só quando há evento
Infraestrutura necessária Basta conseguir chamar a API Uma URL pública sempre no ar
Risco principal Atraso e limite de requisições Perder ou duplicar avisos se o receptor falhar
Bom para Relatórios, sincronizações noturnas, sistemas sem webhook Mensagens, pagamentos, mudanças de status urgentes

Na maioria dos projetos reais, as duas formas aparecem juntas. O webhook avisa que o pedido 1234 foi pago; em seguida, o sistema chama a API para buscar os detalhes completos do pedido. E uma consulta periódica de conferência, uma vez por dia, ajuda a encontrar algum aviso que se perdeu no caminho.

Exemplos do dia a dia

Pedido pago dispara mensagem no WhatsApp

Imagine uma loja de cosméticos do interior paulista que vende pelo site e quer avisar o cliente pelo WhatsApp quando o pagamento for confirmado. O fluxo, passo a passo:

  1. O cliente paga via Pix no checkout.
  2. O intermediador de pagamento confirma a transação e envia um webhook “pagamento aprovado” para a loja virtual.
  3. A loja virtual atualiza o pedido e envia outro webhook, “pedido pago”, para a ferramenta de automação.
  4. A automação chama a API do WhatsApp com um modelo de mensagem aprovado, preenchendo nome do cliente e número do pedido.
  5. A Meta responde que aceitou o pedido de envio e, depois, avisa por webhook as mudanças de status: enviada, entregue e, se o cliente mantiver a confirmação de leitura ativada, lida.

Nesse exemplo há quatro sistemas diferentes, dois webhooks entre eles, uma chamada de API e, no fim, novos webhooks de status. Um detalhe importante: a resposta de sucesso da chamada de API significa que o pedido foi aceito, não que a mensagem chegou. Quem quer saber se o cliente recebeu precisa acompanhar os webhooks de status.

Outro ponto: como a mensagem parte da empresa e, normalmente, o cliente não escreveu nas últimas 24 horas, ela precisa usar um modelo pré-aprovado, assunto dos guias Modelos de mensagem na API do WhatsApp e Janela de atendimento de 24 horas.

Formulário do site vai para o CRM

Uma escola de idiomas recebe interessados por um formulário no site. Ao enviar o formulário, o site dispara um webhook para a ferramenta de integração, que cria o contato no CRM pela API e avisa a equipe comercial. Isso elimina a cópia manual e os leads esquecidos no fim de semana. O artigo Como integrar formulário, planilha e CRM sem retrabalho detalha esse tipo de projeto.

O que pode dar errado e como se preparar

Integrações falham, e um projeto bem feito assume isso desde o começo. Os problemas mais frequentes são previsíveis:

  • Receptor fora do ar. Se o servidor que recebe webhooks cai, os avisos não chegam. Muitas plataformas tentam reenviar por um tempo limitado, que varia conforme o produto. A documentação geral de webhooks da Meta, por exemplo, fala em novas tentativas com frequência decrescente por até 36 horas; passado o prazo, o aviso é descartado.
  • Aviso duplicado. Justamente por causa das novas tentativas, o mesmo evento pode chegar duas vezes. O sistema precisa reconhecer que já processou aquele pagamento para não mandar duas mensagens ao cliente. Programadores chamam isso de idempotência.
  • Ordem trocada. O aviso de “pedido enviado” pode chegar antes do “pedido pago”. Fluxos que dependem de sequência precisam tratar esse caso.
  • Limite de requisições. APIs costumam limitar quantas chamadas cada cliente faz por minuto. Uma automação que consulta demais pode ser bloqueada temporariamente, normalmente com o código 429.
  • Token expirado. Um token que vence sem renovação faz a integração parar sem nenhum erro visível para o atendimento, até que um cliente reclame.

A defesa comum a todos esses casos é ter registro (log) de cada evento recebido e de cada chamada feita, com alerta quando os erros se acumulam. Sem isso, a empresa descobre a falha pelo cliente.

Cuidados de segurança

Integrações levam dados de clientes de um sistema para outro, e cada passagem é um ponto onde algo pode vazar. A Lei Geral de Proteção de Dados exige que quem trata dados pessoais adote medidas de segurança técnicas e administrativas adequadas (art. 46 da Lei 13.709/2018), e isso inclui as conexões entre sistemas. Os cuidados mais importantes:

Com tokens e chaves

  • Guardar tokens em local próprio para segredos (cofre de senhas ou configuração protegida do servidor), nunca em planilha, e-mail ou código compartilhado.
  • Usar um token por integração, com o mínimo de permissões. Se um vazar, o estrago fica restrito.
  • Saber quem tem acesso a cada token e trocar os afetados quando um prestador ou funcionário com acesso sai do projeto.

Com webhooks

  • Exigir HTTPS na URL que recebe os avisos. A Meta, por exemplo, exige HTTPS com certificado válido e não aceita certificados autoassinados.
  • Validar a origem de cada aviso. Como a URL do webhook é pública, qualquer pessoa que a descubra pode enviar dados falsos. Plataformas sérias assinam cada envio com um código secreto; a Meta envia a assinatura no cabeçalho X-Hub-Signature-256, calculada com a chave secreta do aplicativo, e o receptor refaz o cálculo para conferir antes de confiar no conteúdo.
  • Não executar ações sensíveis, como liberar um produto, apenas com base no webhook, sem conferir o status pela API.

Com os dados em si

  • Trafegar apenas os campos necessários. Se a mensagem de confirmação usa nome e número do pedido, o CPF não precisa passar pela automação.
  • Evitar que logs guardem dados pessoais completos por tempo indeterminado.
  • Registrar quais sistemas recebem quais dados, informação útil para responder pedidos de titulares. O artigo LGPD no atendimento digital aprofunda essas obrigações.

Dica: peça ao fornecedor uma lista de todos os tokens, chaves e URLs de webhook criados para o seu projeto, com a conta em que cada um foi gerado. Se algum estiver ligado ao e-mail pessoal de um prestador, transfira para uma conta da empresa antes de considerar o projeto entregue.

Perguntas para fazer a um fornecedor

Você não precisa avaliar código para avaliar uma proposta de integração. As perguntas abaixo revelam rapidamente se o projeto foi pensado com cuidado. Respostas vagas em várias delas são sinal de alerta.

  1. Os sistemas envolvidos têm API oficial e documentada? Algum ponto depende de solução não oficial, como automação de tela ou leitura de e-mail?
  2. Quais eventos chegam por webhook e quais serão consultados periodicamente? Com que intervalo?
  3. O que acontece se o servidor de vocês ficar fora do ar por uma hora? Os eventos são recuperados?
  4. Como evitam processar o mesmo aviso duas vezes?
  5. Os webhooks recebidos têm a origem validada?
  6. Em nome de quem os tokens são gerados e onde ficam guardados? Quem renova os que expiram?
  7. Quais dados pessoais passam pela integração e onde ficam armazenados, inclusive em logs?
  8. Como seremos avisados quando houver erro? Existe painel ou relatório de falhas?
  9. Se encerrarmos o contrato, como recebemos as credenciais e a documentação do que foi construído?

Perguntas frequentes

Todo sistema tem API?

Não. Muitos sistemas mais antigos ou muito simples não oferecem API, ou oferecem apenas parte das funções. Nesses casos, as alternativas costumam ser exportação e importação de arquivos, integrações prontas do próprio fornecedor ou, em último caso, soluções não oficiais, que são mais frágeis. Vale confirmar isso antes de contratar qualquer projeto.

Preciso de um programador para usar webhooks?

Nem sempre. Ferramentas de automação sem código oferecem URLs prontas para receber webhooks e conectar a outros serviços, o que resolve fluxos simples. Para volumes altos, regras complexas ou dados sensíveis, um profissional técnico costuma ser necessário para garantir tratamento de erros, validação de origem e segurança.

Webhook é mais seguro que API?

Nenhum dos dois é seguro ou inseguro por natureza. A API depende de proteger bem os tokens; o webhook depende de validar a origem dos avisos e de usar HTTPS. Os riscos são diferentes, e um projeto bem feito trata os dois.

Conclusão

API é a forma de pedir algo a um sistema; webhook é a forma de um sistema avisar que algo aconteceu. Tokens controlam quem pode pedir, eventos definem quando o aviso é enviado, e a maioria das automações úteis combina os dois. Com esse vocabulário, fica mais fácil desenhar um fluxo, entender uma proposta e cobrar os cuidados de segurança que protegem os dados dos seus clientes.

Se quiser ver como a Telep organiza projetos de integração, da definição dos eventos à entrega das credenciais, a página Como funciona descreve as etapas.