{"id":9992,"date":"2026-08-05T08:00:00","date_gmt":"2026-08-05T11:00:00","guid":{"rendered":"https:\/\/z-api.io\/?p=9992"},"modified":"2026-09-24T12:09:17","modified_gmt":"2026-09-24T15:09:17","slug":"como-usar-webhooks-do-whatsapp-para-criar-automacoes-em-tempo-real-com-o-z-api","status":"publish","type":"post","link":"https:\/\/z-api.io\/blog\/como-usar-webhooks-do-whatsapp-para-criar-automacoes-em-tempo-real-com-o-z-api\/","title":{"rendered":"Como usar webhooks do WhatsApp para criar automa\u00e7\u00f5es em tempo real com o Z-API"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Existe um recurso t\u00e9cnico que deixa toda automa\u00e7\u00e3o mais inteligente e eficiente: <strong>s\u00e3o os webhooks do WhatsApp.<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Na pr\u00e1tica, s\u00e3o os webhooks que permitem que seu sistema saiba, em tempo real, que uma mensagem chegou. Sem eles, sua integra\u00e7\u00e3o fica cega: <strong>n\u00e3o sabe quando o cliente escreveu, n\u00e3o consegue responder automaticamente e n\u00e3o consegue acionar os fluxos que dependem da intera\u00e7\u00e3o do usu\u00e1rio<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um webhook \u00e9 um recurso usado na internet para que uma aplica\u00e7\u00e3o se comunique com outra, fornecendo dados em tempo real sempre que um evento acontecer.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Dessa forma, os dois sistemas realizam trocas de informa\u00e7\u00f5es sem que nenhuma a\u00e7\u00e3o externa precise ser realizada.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Toda vez que o n\u00famero conectado receber ou gerar uma intera\u00e7\u00e3o, o<strong> Z-API faz uma requisi\u00e7\u00e3o com o m\u00e9todo POST para a URL configurada previamente, com um corpo em JSON espec\u00edfico para cada tipo de evento<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Neste artigo, vamos falar mais sobre como os webhooks do Z-API funcionam, quais est\u00e3o dispon\u00edveis, como configurar cada um e como us\u00e1-los para construir automa\u00e7\u00f5es confi\u00e1veis em tempo real.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">O que s\u00e3o webhooks do WhatsApp e qual a fun\u00e7\u00e3o nas automa\u00e7\u00f5es?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Antes de entrar nos detalhes t\u00e9cnicos, vale consolidar o conceito: <strong>um webhook \u00e9 uma URL do seu servidor que o Z-API chama automaticamente sempre que um evento acontece na inst\u00e2ncia<\/strong>.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Quando uma mensagem \u00e9 recebida, quando uma mensagem enviada \u00e9 entregue, quando a inst\u00e2ncia desconecta ou quando o status de um chat muda, o Z-API envia um payload HTTP POST para a URL que voc\u00ea configurou com todos os detalhes do evento.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A diferen\u00e7a entre polling e webhook \u00e9 fundamental para entender por que webhooks s\u00e3o o modelo correto para automa\u00e7\u00f5es de WhatsApp:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Polling<\/strong>: \u00e9 quando seu sistema pergunta periodicamente para a API: &#8220;tem alguma mensagem nova?&#8221;. A cada 5, 10 ou 30 segundos, uma requisi\u00e7\u00e3o \u00e9 feita, a maioria retorna sem novidade, e quando uma mensagem chega, o sistema s\u00f3 descobre na pr\u00f3xima consulta. Isso gera atraso na resposta, consumo desnecess\u00e1rio de recursos e problemas de escala em opera\u00e7\u00f5es com muitas inst\u00e2ncias.<\/li>\n\n\n\n<li><strong>Webhook<\/strong>: inverte essa l\u00f3gica. Seu sistema n\u00e3o precisa perguntar. O Z-API avisa no momento exato em que o evento acontece, sem atraso, sem desperd\u00edcio de recursos e independente de quantas inst\u00e2ncias est\u00e3o ativas.<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Para automa\u00e7\u00f5es que precisam responder em tempo real, como atendimento, qualifica\u00e7\u00e3o de leads e notifica\u00e7\u00f5es bidirecionais, essa diferen\u00e7a \u00e9 o que separa uma integra\u00e7\u00e3o que funciona de uma que frustra.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um ponto importante da documenta\u00e7\u00e3o oficial: <strong>voc\u00ea n\u00e3o precisa configurar todos os webhooks. Mas quanto mais controle voc\u00ea tiver sobre sua inst\u00e2ncia, mais vai conseguir extrair recursos e desenvolver neg\u00f3cios com o Z-API<\/strong>. Configure os que fazem sentido para o seu caso de uso e expanda conforme a opera\u00e7\u00e3o evolui.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Os webhooks dispon\u00edveis no Z-API<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">A documenta\u00e7\u00e3o do Z-API organiza os webhooks do WhatsApp em quatro tipos principais, cada um com fun\u00e7\u00e3o espec\u00edfica:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Delivery (Ao enviar)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de delivery \u00e9 respons\u00e1vel por avisar que sua mensagem foi entregue ao WhatsApp. Importante: <strong>isso n\u00e3o significa necessariamente que o contato a recebeu. Para informa\u00e7\u00f5es de recebimento e leitura, \u00e9 necess\u00e1rio observar o webhook de status<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O endpoint para configurar esse webhook \u00e9:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/update-webhook-delivery<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O payload de retorno desse webhook inclui os seguintes campos:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>phone<\/strong>: n\u00famero de telefone de destino da mensagem<\/li>\n\n\n\n<li><strong>zaapId<\/strong>: identificador da mensagem na conversa<\/li>\n\n\n\n<li><strong>messageId<\/strong>: identificador da mensagem no WhatsApp<\/li>\n\n\n\n<li><strong>instanceId<\/strong>: identificador da inst\u00e2ncia<\/li>\n\n\n\n<li><strong>momment<\/strong>: timestamp em milissegundos do momento em que o evento foi disparado<\/li>\n\n\n\n<li><strong>type<\/strong>: tipo do evento, nesse caso DeliveryCallback<\/li>\n\n\n\n<li><strong>error<\/strong>: presente apenas em casos de erro, cont\u00e9m a descri\u00e7\u00e3o do problema ocorrido no envio<\/li>\n<\/ul>\n\n\n\n<p class=\"wp-block-paragraph\">Um exemplo de retorno de sucesso:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">json<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">{<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;phone&#8221;: &#8220;554499999999&#8221;,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;zaapId&#8221;: &#8220;A20DA9C0183A2D35A260F53F5D2B9244&#8221;,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;messageId&#8221;: &#8220;A20DA9C0183A2D35A260F53F5D2B9244&#8221;,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;instanceId&#8221;: &#8220;instance.id&#8221;,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;momment&#8221;: 1777494009341,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;type&#8221;: &#8220;DeliveryCallback&#8221;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">}<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Esse webhook \u00e9 especialmente \u00fatil para sistemas que precisam confirmar que a mensagem chegou ao WhatsApp antes de acionar o pr\u00f3ximo passo do fluxo, como uma atualiza\u00e7\u00e3o de status no CRM ou o disparo de uma etapa subsequente na automa\u00e7\u00e3o.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Para ver todos os exemplos de retorno por situa\u00e7\u00e3o, incluindo cen\u00e1rios de erro, consulte a <a href=\"https:\/\/developer.z-api.io\/webhooks\/on-message-send-examples\" target=\"_blank\" rel=\"noreferrer noopener\">p\u00e1gina de exemplos de retorno de Ao enviar<\/a> na documenta\u00e7\u00e3o oficial.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Receive (Ao receber)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Este \u00e9 o webhook mais usado em automa\u00e7\u00f5es. Ele \u00e9 chamado toda vez que algu\u00e9m interage com o n\u00famero conectado no WhatsApp, ou seja, toda vez que uma mensagem chega.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O endpoint para configurar esse webhook \u00e9:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/update-webhook-received<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um detalhe importante da documenta\u00e7\u00e3o: esse webhook tamb\u00e9m \u00e9 executado quando a inst\u00e2ncia est\u00e1 configurada para notificar mensagens enviadas pelo pr\u00f3prio n\u00famero, o que veremos na se\u00e7\u00e3o sobre o webhook update-notify-sent-by-me.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Outro ponto relevante para quem trabalha com m\u00eddias: <strong>os arquivos de m\u00eddia, como imagens, documentos e \u00e1udios, ficam dispon\u00edveis por 30 dias no armazenamento do Z-API<\/strong>.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Ap\u00f3s esse prazo, os arquivos s\u00e3o removidos. Isso precisa ser considerado em arquiteturas que dependem de processamento posterior de m\u00eddias.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de recebimento suporta todos os tipos de mensagem do WhatsApp.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Para ver os exemplos de payload por tipo de mensagem, incluindo texto, imagem, \u00e1udio, documento, localiza\u00e7\u00e3o, contato, enquete e bot\u00f5es, consulte a <a href=\"https:\/\/developer.z-api.io\/webhooks\/on-message-received-examples\" target=\"_blank\" rel=\"noreferrer noopener\">p\u00e1gina de exemplos de retorno de Ao receber<\/a> na documenta\u00e7\u00e3o oficial.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Status<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de status avisa sobre todas as mudan\u00e7as de status que uma mensagem sofre: <strong>se foi recebida, lida, respondida ou exclu\u00edda<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um ponto importante da documenta\u00e7\u00e3o: <strong>uma mesma mensagem pode passar por v\u00e1rios status e at\u00e9 ter o mesmo status mais de uma vez, como \u00e9 o caso de &#8220;respondida&#8221;<\/strong>.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Isso significa que seu sistema precisa estar preparado para receber m\u00faltiplos eventos de status para a mesma mensagem e trat\u00e1-los de acordo com a l\u00f3gica de neg\u00f3cio correta.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Esse webhook \u00e9 fundamental para sistemas que precisam saber se o cliente leu a mensagem antes de acionar o pr\u00f3ximo passo, como um follow-up autom\u00e1tico apenas para quem n\u00e3o leu, ou uma atualiza\u00e7\u00e3o de status no CRM quando a mensagem \u00e9 confirmada como lida.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Disconnected (Ao desconectar)<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Esse webhook \u00e9 chamado sempre que o Z-API identifica alguma indisponibilidade na comunica\u00e7\u00e3o, seja do celular com o WhatsApp ou da conex\u00e3o entre o celular e o Z-API.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Para opera\u00e7\u00f5es em produ\u00e7\u00e3o, monitorar eventos de desconex\u00e3o \u00e9 essencial,<strong> j\u00e1 que uma inst\u00e2ncia desconectada sem detec\u00e7\u00e3o significa que mensagens chegam mas n\u00e3o s\u00e3o processadas, e a opera\u00e7\u00e3o para sem que ningu\u00e9m perceba<\/strong>.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Com o webhook de desconex\u00e3o configurado, seu sistema recebe o alerta imediatamente e pode acionar o processo de reconex\u00e3o automaticamente.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Webhook de mensagens enviadas no WhatsApp: <a href=\"https:\/\/z-api.io\/blog\/webhook-mensagens-enviadas-whatsapp\/\" target=\"_blank\" rel=\"noreferrer noopener\">aproveite e veja como isso melhora a opera\u00e7\u00e3o na pr\u00e1tica.<\/a><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Como configurar os webhooks no Z-API?<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">A documenta\u00e7\u00e3o do Z-API oferece dois caminhos para configurar webhooks:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Via painel<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Acesse o painel admin, em Inst\u00e2ncias clique no \u00edcone de visualiza\u00e7\u00e3o da inst\u00e2ncia desejada e nos tr\u00eas pontos escolha &#8220;<strong>editar<\/strong>&#8220;. O campo de webhook aparece na tela de edi\u00e7\u00e3o da inst\u00e2ncia.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Via API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Cada webhook tem seu pr\u00f3prio endpoint de configura\u00e7\u00e3o via PUT. Voc\u00ea passa a URL do seu sistema no campo value do body da requisi\u00e7\u00e3o.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um ponto cr\u00edtico da documenta\u00e7\u00e3o: <strong>o Z-API n\u00e3o aceita webhooks que n\u00e3o sejam HTTPS. Antes de configurar qualquer webhook, certifique-se de que a URL do seu endpoint tem certificado SSL v\u00e1lido<\/strong>.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Em desenvolvimento local, ferramentas como ngrok permitem criar um t\u00fanel HTTPS tempor\u00e1rio para testes.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Atualizar todos os webhooks de uma vez<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Para quem quer apontar todos os webhooks para a mesma URL de forma simples, o Z-API oferece um endpoint espec\u00edfico:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/update-all-webhooks<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O body aceita dois campos:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">json<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">{<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;value&#8221;: &#8220;https:\/\/endereco-do-seu-sistema.com.br\/instancia\/SUA_INSTANCIA\/webhook&#8221;,<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;notifySentByMe&#8221;: true<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">}<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O campo value define a URL para todos os webhooks. O campo notifySentByMe \u00e9 opcional e habilita notifica\u00e7\u00f5es de webhook para mensagens recebidas e enviadas pelo pr\u00f3prio n\u00famero, o que \u00e9 detalhado na pr\u00f3xima se\u00e7\u00e3o.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Esse endpoint \u00e9 especialmente \u00fatil no momento de setup inicial ou <strong>quando voc\u00ea precisa migrar todos os webhooks para uma nova URL sem precisar chamar cada endpoint individualmente<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">A funcionalidade notifySentByMe: o que \u00e9 e quando usar<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Essa \u00e9 uma configura\u00e7\u00e3o que merece aten\u00e7\u00e3o especial porque muda o comportamento padr\u00e3o do webhook de recebimento.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Por padr\u00e3o, o webhook Ao receber notifica apenas mensagens enviadas por outros para o seu n\u00famero. Com a funcionalidade notifySentByMe habilitada, ele passa a notificar tamb\u00e9m as mensagens enviadas pelo pr\u00f3prio n\u00famero conectado.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O endpoint para configurar isso individualmente \u00e9:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{id}\/token\/{token}\/update-notify-sent-by-me<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Com o body:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">json<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">{<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;notifySentByMe&#8221;: true<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">}<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Um aviso importante da documenta\u00e7\u00e3o: para que essa funcionalidade opere corretamente, \u00e9 necess\u00e1rio ter um webhook configurado para o evento Ao receber. Sem isso, n\u00e3o h\u00e1 onde as notifica\u00e7\u00f5es ser\u00e3o entregues.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Quando essa funcionalidade faz sentido?<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Em sistemas de atendimento multiagente, onde diferentes atendentes enviam mensagens pelo mesmo n\u00famero, habilitar notifySentByMe permite que o sistema registre todas as mensagens enviadas, independente de quem enviou.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Isso garante que o hist\u00f3rico de conversas no CRM seja completo, incluindo as mensagens que partiram da empresa para o cliente<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Em arquiteturas de auditoria, onde \u00e9 necess\u00e1rio registrar toda a comunica\u00e7\u00e3o que passou pelo n\u00famero, essa funcionalidade garante que nenhuma mensagem fique de fora do log.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Em sistemas de sincroniza\u00e7\u00e3o entre m\u00faltiplos dispositivos, o notifySentByMe permite que o sistema saiba o que foi enviado em cada sess\u00e3o e mantenha o estado consistente.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Aproveite e confira tamb\u00e9m: <a href=\"https:\/\/z-api.io\/blog\/lid-no-whatsapp-e-como-funciona\/\" target=\"_blank\" rel=\"noreferrer noopener\">o que \u00e9 LID no WhatsApp, como funciona e o que muda nas integra\u00e7\u00f5es com a API do Z-API.<\/a><\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Como configurar o webhook de recebimento: passo a passo<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Aqui est\u00e1 o fluxo completo para colocar o webhook de recebimento funcionando em produ\u00e7\u00e3o:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">1. Criar o endpoint no seu sistema<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Seu servidor precisa expor uma URL HTTPS que aceite requisi\u00e7\u00f5es POST. Esse endpoint recebe os payloads do Z-API e precisa responder com status 200 para confirmar o recebimento.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">2. Configurar a URL no Z-API<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Fa\u00e7a uma requisi\u00e7\u00e3o PUT para o endpoint de configura\u00e7\u00e3o com a URL do seu sistema:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{instanceId}\/token\/{token}\/update-webhook-received<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Body:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">{<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;value&#8221;: &#8220;https:\/\/endereco-do-seu-sistema.com.br\/instancia\/SUA_INSTANCIA\/receive&#8221;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">}<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">3. Processar o payload recebido<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Quando uma mensagem chega no n\u00famero conectado, o Z-API faz um POST para a URL configurada com o payload da mensagem. Seu sistema extrai os campos relevantes, processa a mensagem e executa a l\u00f3gica de neg\u00f3cio correspondente.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">4. Habilitar notifySentByMe se necess\u00e1rio<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Se o seu caso de uso exige receber notifica\u00e7\u00f5es tamb\u00e9m das mensagens enviadas pelo n\u00famero, configure:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">PUT https:\/\/api.z-api.io\/instances\/{id}\/token\/{token}\/update-notify-sent-by-me<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Body:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">{<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">&nbsp;&nbsp;&#8220;notifySentByMe&#8221;: true<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">}<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Casos de uso onde webhooks fazem toda a diferen\u00e7a<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Com os webhooks do WhatsApp configurados corretamente, esses s\u00e3o os casos de uso que se tornam poss\u00edveis em produ\u00e7\u00e3o:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Atendimento em tempo real com agente de IA<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de recebimento \u00e9 o gatilho de toda automa\u00e7\u00e3o inteligente no WhatsApp. Quando a mensagem chega, o payload \u00e9 enviado ao sistema, o LLM processa o conte\u00fado e a resposta \u00e9 enviada de volta via Z-API.\u00a0<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Sem o webhook de recebimento funcionando de forma confi\u00e1vel, o agente n\u00e3o consegue operar em tempo real<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Confirma\u00e7\u00e3o de entrega e leitura no CRM<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de delivery confirma que a mensagem chegou ao WhatsApp. O webhook de status confirma quando foi recebida e lida pelo destinat\u00e1rio. <strong>Com esses dois eventos sendo processados, o CRM pode ser atualizado automaticamente com o status real de cada comunica\u00e7\u00e3o, sem nenhuma interven\u00e7\u00e3o manual<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Detec\u00e7\u00e3o e recupera\u00e7\u00e3o autom\u00e1tica de desconex\u00e3o<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O webhook de desconex\u00e3o permite que o sistema identifique imediatamente quando uma inst\u00e2ncia perde a conex\u00e3o e acione o processo de reconex\u00e3o automaticamente, minimizando o tempo de inatividade da opera\u00e7\u00e3o.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Hist\u00f3rico completo de conversas<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Com notifySentByMe habilitado, o sistema registra tanto as mensagens recebidas quanto as enviadas, construindo um hist\u00f3rico completo de cada conversa que pode ser consultado por qualquer atendente no CRM.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Automa\u00e7\u00f5es bidirecionais<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Uma notifica\u00e7\u00e3o \u00e9 enviada ao cliente via Z-API. Quando o cliente responde, o webhook de recebimento entrega essa resposta ao sistema. O sistema processa e aciona a pr\u00f3xima etapa do fluxo automaticamente. O ciclo completo acontece sem nenhuma interven\u00e7\u00e3o humana.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Boas pr\u00e1ticas para garantir confiabilidade em produ\u00e7\u00e3o<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">A configura\u00e7\u00e3o dos webhooks \u00e9 o primeiro passo. Garantir que funcionem de forma confi\u00e1vel em produ\u00e7\u00e3o exige algumas pr\u00e1ticas adicionais:<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Responder 200 rapidamente<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">O endpoint precisa responder com status 200 imediatamente ao receber o payload. Se o processamento for demorado, delegue para uma fila ass\u00edncrona e responda 200 antes de processar. <strong>Se o endpoint demorar demais para responder, o Z-API pode interpretar como falha<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Tratar duplicatas com idempot\u00eancia<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Em casos de instabilidade de rede, o Z-API pode reenviar o mesmo evento. Use o identificador \u00fanico da mensagem presente no payload para verificar se o evento j\u00e1 foi processado antes de executar qualquer a\u00e7\u00e3o. <strong>Processar a mesma mensagem duas vezes pode gerar respostas duplicadas ao cliente<\/strong>.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Usar HTTPS obrigatoriamente<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">A documenta\u00e7\u00e3o \u00e9 clara: <strong>o Z-API n\u00e3o aceita webhooks que n\u00e3o sejam HTTPS<\/strong>. Certifique-se de que o endpoint tem certificado SSL v\u00e1lido antes de configurar qualquer webhook.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Monitorar a sa\u00fade dos endpoints<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Configurar alertas para quando os webhooks pararem de receber eventos \u00e9 fundamental para detectar falhas de configura\u00e7\u00e3o ou problemas de infraestrutura antes que afetem a opera\u00e7\u00e3o.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">N\u00e3o compartilhar ID e token<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">A documenta\u00e7\u00e3o do Z-API refor\u00e7a: <strong>nunca compartilhe o ID e o token da inst\u00e2ncia com ningu\u00e9m<\/strong>. Esses dados d\u00e3o acesso completo \u00e0 inst\u00e2ncia e precisam ser tratados como credenciais sens\u00edveis.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Recursos da documenta\u00e7\u00e3o para aprofundar<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Para quem quer ir al\u00e9m do b\u00e1sico, a documenta\u00e7\u00e3o oficial do Z-API tem recursos complementares que cobrem casos mais avan\u00e7ados:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A <a href=\"https:\/\/developer.z-api.io\/webhooks\/on-message-send-examples\">p\u00e1gina de exemplos de retorno de Ao enviar<\/a> detalha todos os cen\u00e1rios poss\u00edveis no webhook de delivery, incluindo os diferentes tipos de erro que podem aparecer no campo error do payload.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A <a href=\"https:\/\/developer.z-api.io\/webhooks\/on-message-received-examples\" target=\"_blank\" rel=\"noreferrer noopener\">p\u00e1gina de exemplos de retorno de Ao receber<\/a> tem exemplos de payload para cada tipo de mensagem suportada: texto, imagem, \u00e1udio, v\u00eddeo, documento, localiza\u00e7\u00e3o, contato, enquete, bot\u00f5es e mais.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">A <a href=\"https:\/\/developer.z-api.io\/webhooks\/introduction\" target=\"_blank\" rel=\"noreferrer noopener\">introdu\u00e7\u00e3o aos webhooks<\/a> tem o overview completo de todos os tipos dispon\u00edveis e as instru\u00e7\u00f5es de configura\u00e7\u00e3o via painel e via API.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O endpoint de <a href=\"https:\/\/developer.z-api.io\/webhooks\/update-every-webhooks\" target=\"_blank\" rel=\"noreferrer noopener\">atualizar todos os webhooks<\/a> \u00e9 \u00fatil especialmente em setup inicial ou migra\u00e7\u00f5es, quando \u00e9 necess\u00e1rio apontar todos os webhooks para uma nova URL de uma vez.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Conclus\u00e3o<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">Os webhooks do WhatsApp s\u00e3o a funda\u00e7\u00e3o t\u00e9cnica de qualquer automa\u00e7\u00e3o que precisa operar em tempo real.&nbsp;<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">O <a href=\"https:\/\/z-api.io\/\" target=\"_blank\" rel=\"noreferrer noopener\">Z-API<\/a> oferece um conjunto completo de webhooks que cobre todos os eventos relevantes de uma opera\u00e7\u00e3o:<strong> recebimento de mensagens, confirma\u00e7\u00e3o de entrega, mudan\u00e7as de status, desconex\u00e3o da inst\u00e2ncia e mensagens enviadas pelo pr\u00f3prio n\u00famero<\/strong>.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Configurar corretamente, usar HTTPS, responder 200 rapidamente, tratar duplicatas e monitorar a sa\u00fade dos endpoints s\u00e3o as pr\u00e1ticas que transformam um webhook funcional em uma infraestrutura confi\u00e1vel de longo prazo.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Para quem est\u00e1 construindo automa\u00e7\u00f5es com o Z-API, a documenta\u00e7\u00e3o oficial tem tudo que \u00e9 necess\u00e1rio para implementar cada webhook com precis\u00e3o, desde os endpoints de configura\u00e7\u00e3o at\u00e9 os exemplos completos de payload por tipo de evento.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Acesse a documenta\u00e7\u00e3o de webhooks do Z-API e teste na pr\u00e1tica. \ud83d\udc49 <a href=\"https:\/\/app.z-api.io\/app\/auth\/new-account\" target=\"_blank\" rel=\"noreferrer noopener\">Crie sua conta gr\u00e1tis<\/a> \ud83d\udcc4 <a href=\"https:\/\/developer.z-api.io\/webhooks\/introduction\" target=\"_blank\" rel=\"noreferrer noopener\">Documenta\u00e7\u00e3o de webhooks<\/a><\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><\/p>\n\n\n<div class=\"kk-star-ratings kksr-auto kksr-align-right kksr-valign-bottom\"\n    data-payload='{&quot;align&quot;:&quot;right&quot;,&quot;id&quot;:&quot;9992&quot;,&quot;slug&quot;:&quot;default&quot;,&quot;valign&quot;:&quot;bottom&quot;,&quot;ignore&quot;:&quot;&quot;,&quot;reference&quot;:&quot;auto&quot;,&quot;class&quot;:&quot;&quot;,&quot;count&quot;:&quot;1&quot;,&quot;legendonly&quot;:&quot;&quot;,&quot;readonly&quot;:&quot;&quot;,&quot;score&quot;:&quot;5&quot;,&quot;starsonly&quot;:&quot;&quot;,&quot;best&quot;:&quot;5&quot;,&quot;gap&quot;:&quot;5&quot;,&quot;greet&quot;:&quot;Avalie este post&quot;,&quot;legend&quot;:&quot;5\\\/5 - (1 voto)&quot;,&quot;size&quot;:&quot;24&quot;,&quot;title&quot;:&quot;Como usar webhooks do WhatsApp para criar automa\u00e7\u00f5es em tempo real com o Z-API&quot;,&quot;width&quot;:&quot;142.5&quot;,&quot;_legend&quot;:&quot;{score}\\\/{best} - ({count} {votes})&quot;,&quot;font_factor&quot;:&quot;1.25&quot;}'>\n            \n<div class=\"kksr-stars\">\n    \n<div class=\"kksr-stars-inactive\">\n            <div class=\"kksr-star\" data-star=\"1\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" data-star=\"2\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" data-star=\"3\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" data-star=\"4\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" data-star=\"5\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n    <\/div>\n    \n<div class=\"kksr-stars-active\" style=\"width: 142.5px;\">\n            <div class=\"kksr-star\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n            <div class=\"kksr-star\" style=\"padding-right: 5px\">\n            \n\n<div class=\"kksr-icon\" style=\"width: 24px; height: 24px;\"><\/div>\n        <\/div>\n    <\/div>\n<\/div>\n                \n\n<div class=\"kksr-legend\" style=\"font-size: 19.2px;\">\n            5\/5 - (1 voto)    <\/div>\n    <\/div>\n","protected":false},"excerpt":{"rendered":"<p>Entenda o que s\u00e3o webhooks do WhatsApp, como configurar com o Z-API e como us\u00e1-los para construir automa\u00e7\u00f5es em tempo real neste guia completo.<\/p>\n","protected":false},"author":16,"featured_media":10538,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"content-type":"","footnotes":""},"categories":[22,5],"tags":[49],"class_list":["post-9992","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-automacao-de-mensagens","category-tutoriais","tag-webhooks-do-whatsapp"],"_links":{"self":[{"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/posts\/9992","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/users\/16"}],"replies":[{"embeddable":true,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/comments?post=9992"}],"version-history":[{"count":2,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/posts\/9992\/revisions"}],"predecessor-version":[{"id":11039,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/posts\/9992\/revisions\/11039"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/media\/10538"}],"wp:attachment":[{"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/media?parent=9992"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/categories?post=9992"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/z-api.io\/blog\/wp-json\/wp\/v2\/tags?post=9992"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}