Solução de problemas: webhook sem eventos, erros de auth da API e OAuth
Como diagnosticar webhooks que não disparam, erros 401/403 da API REST e falhas de conexão OAuth nas integrações.
Veja este passo no vídeo · Solução de problemas
Nota: os conectores OAuth da galeria (Gmail, Outlook, HubSpot, Salesforce, Shopify, Google Sheets, Google Meet, Calendly, Stripe Payments, Zoom, Microsoft Teams, DocuSign, Dropbox Sign, PandaDoc e Notion) estão em Em breve: em Configurações → Integrações os cartões deles aparecem como «Em breve» e ainda não podem ser conectados. A seção de OAuth deste guia vai valer quando estiverem disponíveis. Os webhooks e a API REST funcionam hoje (a partir do plano Crece); para conectar outras ferramentas enquanto isso, use n8n, Make ou Zapier.
Para que serve
Este guia resolve os três problemas mais comuns ao integrar o Omnifox por API: um webhook que não recebe eventos, erros de autenticação na API REST v1 e falhas de OAuth ao conectar integrações (Gmail, Outlook, HubSpot, etc.).
O webhook não recebe eventos
- Confirme a assinatura:
GET /v1/webhooks/{webhook}e verifique seis_activeétruee se o seu evento está emevents. - Revise os logs de entrega retornados por esse mesmo endpoint: se houver tentativas com código
4xx/5xx, o problema está no seu servidor (não no Omnifox). - Responda 2xx rápido: seu endpoint deve responder
200dentro detimeout_seconds. Se demorar, o Omnifox conta como falha e tenta novamente atéretry_count. - URL pública por HTTPS: a URL precisa estar acessível pela internet com certificado válido.
localhostou IPs privados não recebem entregas. - Verifique a assinatura corretamente: calcule
HMAC-SHA256(body, signing_secret)e compare comX-Omnifox-Signature. Se você rotacionou o segredo (rotate-secret), atualize o valor no seu servidor. - O nome do evento é exato: use os nomes do catálogo exatamente (ex.:
message.received, nãomessage_received).
Erros de auth da API (401 / 403)
- 401 Unauthorized: o token Bearer está ausente, digitado errado ou foi revogado. Envie
Authorization: Bearer 123_aBc...(o valor completo do token;omf_é apenas o prefixo visível na lista) e verifique a key em Configurações → Chaves API. - 403 Forbidden: o token é válido mas aponta para outro workspace. Cada token tem escopo de um único workspace; gere um token para o workspace certo ou use o
workspace_idcorrespondente. - 404 em um recurso que existe: o ID provavelmente pertence a outro workspace (o escopo o oculta), em vez de estar ausente.
- 422 Validation error: faltam campos obrigatórios no body; a resposta lista os campos inválidos.
- 429 Too Many Requests: você excedeu o limite de requisições por minuto do seu plano (ex.: 1.200 por minuto no Crece; veja Limites de taxa (rate limits) da API e cabeçalhos de cota); aplique backoff exponencial.
Falhas de OAuth ao conectar integrações (quando estiverem disponíveis)
- O cartão mostra «Em breve»: esse conector ainda não está habilitado no Omnifox; não é um erro da sua conta. Enquanto isso, use n8n, Make ou Zapier.
- "Selecione um workspace antes de conectar": escolha o workspace no seletor superior e tente de novo.
- "A sessão OAuth expirou. Tente novamente": o fluxo demorou demais entre Conectar e o callback; reinicie pelo cartão.
- redirect_uri_mismatch (Google/Microsoft): a URL de callback registrada no app do provedor não coincide com a do Omnifox. Peça ao administrador para alinhar os Authorized redirect URIs.
- Conecta mas para de sincronizar (Gmail): o refresh token não foi emitido; Desconecte e Conecte de novo para forçar um novo consentimento.
Verificação
- Webhook: dispare um evento real (crie um contato) e veja os logs de entrega — deve aparecer um
200. - API:
GET /v1/teamscom seu token deve responder200. - OAuth: o cartão da integração deve mostrar Conectado com a conta.
Dicas
- Sempre registre o corpo bruto de cada webhook recebido: facilita comparar a assinatura.
- Mantenha um token de API por sistema externo; assim você pode revogar um sem quebrar os demais.
Artigos relacionados
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.