Pular para o conteúdo principal

​
O que são webhooks?

Webhooks são notificações HTTP que o Omni Z-API envia ao seu servidor quando eventos acontecem — como uma mensagem recebida, status de entrega, ou uma atualização de template. Em vez de o seu sistema consultar a API periodicamente (polling), o Omni Z-API envia os eventos para você assim que acontecem.
Qualquer secret key válida de um workspace ativo pode gerenciar webhooks, de canal e de template. Não é preciso nenhuma role específica na conta. Se o workspace não estiver ativo, as chamadas de webhook retornam 422 com {"error": "Webhook management requires an active workspace"}.

​
Tipos de webhook

O Omni Z-API tem três tipos de webhook. O que muda entre eles são os eventos aceitos e a forma de associação — cada seção detalha as suas particularidades. O restante desta página vale para os três tipos.

Webhooks de canal

Recebem os eventos de um canal específico (mensagens, entrega, conexão).

Webhooks de template

Recebem os eventos de template do WhatsApp, independentes de instância.

Webhook padrão

Recebe os eventos de todos os canais do workspace que não têm webhook próprio.

​
Formatos de payload

O Omni Z-API suporta três formatos de payload:
payloadFormat vale apenas para webhooks de canal. Nos webhooks de template o formato é sempre DEFAULT e o campo é descartado.

​
URL do webhook

Ao criar um webhook, e ao trocar a URL de um webhook existente, o Omni Z-API confere a url antes de gravar. As regras valem para os dois tipos de webhook. O host é recusado quando:
  • é um IP que não é público: rede privada, loopback, link-local (inclusive o endereço de metadados de nuvem 169.254.169.254), CGNAT, multicast ou faixa reservada, em IPv4 ou IPv6;
  • é um nome que resolve para um desses endereços. Basta um endereço não público entre os que o nome devolve;
  • é localhost, termina em .localhost ou .internal, ou é um nome sem ponto, como https://servidor/webhook;
  • é um IPv4 escrito fora da forma usual de quatro números decimais, como http://2130706433/;
  • não existe no DNS ou não tem endereço.
Se o DNS não responder a tempo, a resposta é 503 com {"error": "Could not verify the webhook URL now, try again"}. Nada é gravado: tente de novo.
http continua aceito, mas prefira https: com http, o corpo do evento e os headers de autenticação trafegam sem criptografia.
Na atualização, a url só é conferida quando muda. Um PATCH sem url, ou com a mesma URL já gravada, não é recusado por ela: um webhook antigo cuja URL hoje seria recusada continua podendo ser desabilitado, alterado em outros campos ou excluído.

​
Autenticação do webhook

Você pode configurar como o Omni Z-API se autentica ao chamar sua URL:

​
Assinatura HMAC

Para garantir que as requisições recebidas são realmente do Omni Z-API e não foram adulteradas, habilite a assinatura HMAC configurando signing: true ao criar o webhook. Quando habilitado:
  • Um secret de 64 caracteres hexadecimais é gerado e retornado apenas uma vez na criação/atualização.
  • Cada requisição enviada ao seu webhook traz o header x-webhook-signature, no formato t={unix_timestamp},v1={hmac_sha256_hex}.
  • Você verifica a assinatura no seu servidor usando o secret armazenado.
A assinatura não é o HMAC apenas do corpo. Ela é calculada sobre uma string canônica de cinco campos, da qual o corpo é o último. Veja Assinatura HMAC para a string exata, um exemplo completo e código de validação pronto.
O secret é exibido apenas na resposta de criação ou de atualização com signing: true. Armazene-o com segurança — ele não pode ser recuperado depois.