API e webhook: a diferença e como conectar os sistemas do seu negócio
API e webhook conectam sistemas de jeitos opostos: na API você pergunta, no webhook o outro sistema avisa. Veja exemplos, fila, segurança e duplicidade.
Karine Sackt · Designer de landing pages e fundadora da Fysi Lab Digital
· 12 min de leitura

Neste artigo
- API e webhook: a diferença em uma frase
- O que é uma API
- O que é webhook e como funciona
- Exemplos de API e webhook num negócio de serviço
- Como conectar dois sistemas, passo a passo
- Responda rápido e deixe o trabalho pesado para a fila
- O mesmo aviso vai chegar duas vezes
- Segurança do webhook: confira quem está avisando
- Webhook do banco: quando o seu sistema avisa outro
- Onde procurar quando a integração falha
- Conecte os sistemas do seu negócio
- Perguntas frequentes
API e webhook são as duas formas de um sistema conversar com outro, e a diferença está em quem toma a iniciativa. Pela API, o seu sistema pergunta e recebe a resposta. Pelo webhook, o outro sistema avisa o seu assim que algo acontece: o pagamento foi aprovado, o contrato foi assinado, chegou uma mensagem. Para conectar os sistemas de um negócio, você vai usar os dois, e o que faz a conexão funcionar todo dia é o que o seu sistema faz depois de receber cada aviso.
Na Fysi Lab Digital e na Fysi Academy, as compras, os contratos, os formulários e as mensagens passam por webhooks. Neste guia eu explico a diferença com exemplos de um negócio de serviço, o passo a passo para conectar dois sistemas e os três cuidados que eu ensino no Sistemas Sob Medida: responder rápido, aceitar o aviso repetido e conferir quem está avisando.
API e webhook: a diferença em uma frase
Na API, você liga para perguntar. No webhook, o outro lado liga para avisar.
| Ponto | API | Webhook |
|---|---|---|
| Quem inicia | O seu sistema | O outro sistema |
| Quando acontece | Quando o seu sistema precisa de um dado ou quer fazer uma ação | Assim que um evento acontece do outro lado |
| Exemplo | Buscar os posts de um site, criar uma cobrança, enviar uma mensagem | Pagamento aprovado, contrato assinado, formulário enviado |
| O que o seu sistema precisa ter | A chave de acesso do outro serviço | Um endereço público que recebe o aviso |
| Risco mais comum | Perguntar demais e ser barrado pelo limite de pedidos | Receber o mesmo aviso duas vezes |
Uma integração completa costuma usar os dois. O webhook avisa que o contrato foi assinado. O seu sistema recebe, grava e, se precisar de mais detalhes, usa a API do serviço de contrato para buscar o documento.
O que é uma API
API é a porta que um sistema abre para outros sistemas usarem. Ela define o que dá para pedir, em que formato e o que volta. O seu sistema manda um pedido para um endereço, com a chave de acesso, e recebe a resposta, quase sempre em JSON, um formato de texto organizado em campos.
Um exemplo conhecido: o WordPress tem uma REST API que permite a outras aplicações ler e enviar dados do site em JSON (REST API Handbook, consultado em 20/11/2026). É por ela que um sistema externo consegue buscar os posts de um blog ou publicar um conteúdo novo.
Toda resposta de API traz um número de status, e eu ensino os alunos a ler esse número antes de qualquer outra coisa:
- 200: deu certo.
- 401: o serviço não sabe quem está pedindo. A chave está errada ou o login caiu.
- 403: o serviço sabe quem é e recusou a ação por falta de permissão.
- 404: o endereço ou o item não existe.
- 429: pedidos demais em pouco tempo.
- 500: erro dentro do servidor que respondeu.
O que é webhook e como funciona
Webhook é um aviso automático que um sistema manda para o endereço de outro sistema quando um evento acontece. Você cadastra no serviço de pagamento, por exemplo, o endereço do seu sistema que vai receber os avisos. A partir daí, a cada compra aprovada, o serviço envia para esse endereço um pedido com os dados da compra.
O seu sistema precisa de uma rota pronta para receber esse pedido. Ela pode ser uma rota de API no Next.js, uma Edge Function do Supabase, que a documentação indica para receber webhooks e integrar serviços externos (Edge Functions, consultado em 20/11/2026), ou um Worker da Cloudflare, que recebe os pedidos que chegam pela função fetch() e devolve uma resposta (Fetch Handler, consultado em 20/11/2026).
Na Fysi Academy, é assim que a venda vira acesso. Quando alguém compra um curso, o checkout avisa a plataforma por webhook, a plataforma grava a compra, cria a matrícula e manda o e-mail de boas-vindas. Eu não aperto botão nenhum.
Exemplos de API e webhook num negócio de serviço
Estas são as conexões que eu mais vejo fazerem diferença na rotina de quem vende serviço:
- Formulário do site. A pessoa envia o contato pela landing page, o site grava no banco e avisa o responsável por e-mail. Nos meus sites, que são publicados como site estático, quem recebe o envio é uma função que roda no próprio Worker.
- Pagamento aprovado. O serviço de cobrança avisa por webhook, o financeiro marca a parcela como paga e o projeto sai da espera.
- Contrato assinado. O serviço de assinatura avisa, e o sistema abre o projeto e dispara o briefing para o cliente. Na Fysi, contrato e pagamento rodam no Autentique e no Asaas.
- Mensagem no WhatsApp. A API oficial do WhatsApp Business avisa por webhook quando chega mensagem, e o CRM registra o contato na etapa certa (Webhooks do WhatsApp, consultado em 20/11/2026). Eu falo da escolha do caminho de conexão em CRM com IA.
- Linha nova no banco. O seu próprio banco também pode avisar outro sistema. Esse caso tem uma seção própria mais abaixo.
Como conectar dois sistemas, passo a passo
Eu escrevo cada conexão como uma frase antes de pedir qualquer coisa ao Claude Code: "quando X acontecer no sistema A, o sistema B precisa fazer Y". Essa frase vira o escopo da integração.
- Defina quem inicia. Se o evento acontece do outro lado e você precisa saber na hora, é webhook. Se você precisa buscar ou criar algo, é API.
- Leia a documentação do serviço. Ela diz quais eventos existem, o formato do aviso, como ele prova que veio do serviço e quantas vezes ele tenta de novo quando o seu sistema não responde.
- Crie a rota que recebe. Um endereço do seu sistema, só para aquele serviço.
- Confira quem está avisando. Antes de qualquer coisa, a rota valida a senha ou a assinatura que o serviço manda junto.
- Grave o evento. O aviso entra numa tabela de eventos, com a chave que identifica aquele pedido.
- Responda com sucesso. Rápido, para o serviço parar de tentar.
- Faça o trabalho. Liberar acesso, abrir projeto, mandar e-mail, atualizar o CRM.
- Teste com um evento de verdade em ambiente de teste. E depois teste mandando o mesmo evento duas vezes.
O desenho completo de um sistema, com as integrações no lugar certo, está em como criar sistemas para o seu negócio com IA.
Responda rápido e deixe o trabalho pesado para a fila
O serviço que manda o webhook espera uma resposta. Se o seu sistema demora, porque está gerando um PDF ou mandando dezenas de e-mails antes de responder, o serviço entende que o aviso se perdeu e manda de novo.
A saída é separar o recebimento do trabalho. A rota grava o aviso, responde com sucesso e coloca o trabalho demorado numa fila. Uma parte separada do sistema vai pegando as tarefas da fila no ritmo certo. Cada tarefa tem um status (pendente, processando, feito, erro), um contador de tentativas e o horário da próxima tentativa, com uma espera maior a cada falha para dar tempo de o serviço do outro lado voltar.
As ferramentas que eu uso já trazem fila pronta. O Supabase Queues guarda as mensagens no próprio Postgres, com entrega garantida (Supabase Queues, consultado em 20/11/2026). As Cloudflare Queues entregam as mensagens em lotes, com novas tentativas e atraso configuráveis (Batching and retries, consultado em 20/11/2026). Para um sistema pequeno, uma tabela de tarefas no banco, lida por uma tarefa agendada, já resolve.
Fila vale quando o trabalho demora, atinge muita gente de uma vez, depende de um serviço que pode estar fora do ar ou não pode se perder de jeito nenhum, como liberar o acesso de quem pagou.
O mesmo aviso vai chegar duas vezes
Repetir o aviso faz parte do funcionamento do webhook. Quando o serviço não tem certeza de que o seu sistema recebeu, ele manda de novo. Às vezes o seu sistema tinha gravado tudo e só a resposta se perdeu no caminho. Clique duplo num botão e nova tentativa de fila produzem o mesmo efeito.
Se o sistema não estiver preparado, uma compra vira duas matrículas, dois e-mails de boas-vindas e o faturamento do relatório aparece em dobro. A proteção tem três partes:
- A chave do pedido. Um identificador que diz "este aviso é este": o número do pedido que vem no webhook, somado ao tipo do evento. Compra aprovada e reembolso do mesmo pedido são eventos diferentes.
- A regra de valor único no banco. A tabela recusa duas linhas com a mesma chave. Conferir no código antes de gravar deixa passar dois avisos que chegam no mesmo segundo. A regra no banco segura todos.
- O upsert. Quando você quer uma linha só, sempre atualizada, o banco cria a linha se ela ainda não existe e atualiza se já existe. O pedido nasce como pago e, se chegar o reembolso, a mesma linha muda de status.
Na Fysi Academy funciona assim: cada aviso de pagamento é gravado numa tabela de eventos com a chave formada pelo número do pedido e pelo tipo do evento, e essa chave é única. Quando o aviso repetido chega, o sistema responde que recebeu e segue a vida. Cada pessoa tem no máximo uma matrícula por curso, e quem garante isso é o banco.
Segurança do webhook: confira quem está avisando
O endereço que recebe o webhook é público. Qualquer pessoa que descubra esse endereço pode mandar um aviso falso de "pagamento aprovado". Por isso a primeira linha da rota confere a prova de origem que o serviço manda junto, que pode ser uma senha num cabeçalho ou uma assinatura calculada com uma chave secreta. Se a prova não bate, a rota responde 401 e para ali.
Três cuidados que eu reviso em todo projeto:
- Chaves fora do código. A senha do webhook e as chaves de API ficam em variáveis de ambiente, nunca no repositório.
- Chave secreta só no servidor. No Supabase, a chave secreta ignora as regras de acesso do banco e precisa ficar sob o seu controle, enquanto a chave publicável pode ir para o navegador porque só alcança o que as regras permitem (API keys, consultado em 20/11/2026).
- Rota que só faz uma coisa. A rota do webhook de pagamento recebe aviso de pagamento. Cada serviço tem a sua.
Webhook do banco: quando o seu sistema avisa outro
O caminho também funciona ao contrário. No Supabase, os Database Webhooks disparam quando uma linha é inserida, atualizada ou apagada numa tabela e enviam os dados para um endereço externo. Eles são construídos sobre gatilhos do banco com a extensão pg_net, que trabalha de forma assíncrona e não segura a gravação enquanto espera a resposta (Database Webhooks, consultado em 20/11/2026).
Um exemplo de uso: quando uma proposta muda para "aceita", o banco avisa uma função que gera o contrato e manda para assinatura. Quando o contrato volta assinado, o webhook do serviço de assinatura avisa o seu sistema, e o projeto abre sozinho. As duas pontas da conversa ficam automáticas e o banco continua sendo a fonte da verdade.
Onde procurar quando a integração falha
Integração que para costuma deixar pista em quatro lugares, e eu sigo sempre esta ordem:
- O painel do serviço que avisa. Procure o histórico de envios do webhook, com o status que o seu sistema devolveu.
- Os registros da sua rota. Na Vercel, nos logs do projeto. No Supabase, nos logs das funções. No terminal, quando você testa no computador.
- A tabela de eventos. Se o aviso está lá, ele chegou. Se não está, o problema veio antes.
- A tabela de tarefas da fila. As que estão em erro mostram a mensagem do que falhou.
Com o status e a mensagem de erro em mãos, cole tudo no Claude Code contando o que você esperava que acontecesse. Ele encontra o problema muito mais rápido com esses dados do que com "a integração parou".
Conecte os sistemas do seu negócio
No Sistemas Sob Medida, eu ensino a construir e conectar os sistemas do seu negócio com o Claude, com fila, proteção contra pedido duplicado, tarefas agendadas e revisão de segurança. Se você prefere que uma equipe faça as integrações da sua empresa, a Fysi Lab Digital constrói para você.
Perguntas frequentes
Webhook é uma API?
Webhook é uma forma de integração que funciona no sentido inverso da API. Na API, o seu sistema pede. No webhook, o outro sistema envia o aviso para um endereço seu, assim que o evento acontece.
API e webhook é a mesma coisa?
São formas complementares. A API responde quando você pergunta, e o webhook avisa quando algo acontece. Uma integração bem feita costuma usar os dois: o webhook avisa e a API busca o detalhe.
Webhook é seguro?
Fica seguro quando a rota confere a senha ou a assinatura do serviço antes de qualquer ação, as chaves ficam fora do código e o banco tem regra contra pedido duplicado.
Webhook é pago?
O webhook é um recurso do serviço que envia o aviso, e a cobrança depende do plano de cada serviço. Do seu lado, o custo está onde a rota roda e na ferramenta de fila, se você usar uma paga. Confira na página de preços de cada um.
Preciso saber programar para integrar sistemas?
Você precisa saber descrever a integração: o evento, o que o sistema faz com ele e o que acontece se o aviso chegar duas vezes. O Claude Code escreve o código a partir dessa descrição, e você testa cada caminho antes de publicar.















