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.

Jun 26, 2026

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

  1. Confirme a assinatura: GET /v1/webhooks/{webhook} e verifique se is_active é true e se o seu evento está em events.
  2. 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).
  3. Responda 2xx rápido: seu endpoint deve responder 200 dentro de timeout_seconds. Se demorar, o Omnifox conta como falha e tenta novamente até retry_count.
  4. URL pública por HTTPS: a URL precisa estar acessível pela internet com certificado válido. localhost ou IPs privados não recebem entregas.
  5. Verifique a assinatura corretamente: calcule HMAC-SHA256(body, signing_secret) e compare com X-Omnifox-Signature. Se você rotacionou o segredo (rotate-secret), atualize o valor no seu servidor.
  6. O nome do evento é exato: use os nomes do catálogo exatamente (ex.: message.received, não message_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_id correspondente.
  • 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/teams com seu token deve responder 200.
  • 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

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp