Utilize Tokens & Webhooks para gerar credenciais de autenticação e configurar URLs para receber notificações automáticas de eventos, facilitando a integração do Zenvia Customer Cloud com outros sistemas.
Ambos são usados para integrar e interagir via APIs, garantindo uma comunicação segura entre sistemas.
💡 Para configurar e utilizar as APIs, recomendamos o apoio de um desenvolvedor. A documentação completa está disponível no Zenvia APIs.
Como acessar
No menu lateral, clique em Configurações > Tokens & Webhooks.
Criar novo token
O Token é uma chave de autenticação com nossas APIs. É com ela que você realiza as integrações e demais chamadas. Para criar, realize as etapas a seguir na tela Tokens & Webhooks:
- Clique na opção Criar Novo em Tokens;
- Insira um Nome para identificação;
- Escolha o tipo de autenticação:
- Padrão: Utiliza apenas o token para validar a conexão entre sistemas.
- Com assinatura: Incorpora uma assinatura digital ao token, proporcionando uma camada extra de segurança.
- Finalize em Salvar.
💡 Dica: Se preferir, clique sob o botão Baixar.CSV para ter o arquivo com a chave salva.
Caso deseje excluir o Token, retorne à tela de Tokens & Webhooks e clique na opção Excluir.
Criar novo Webhook
Os Webhooks são opcionais e permitem que você receba eventos na URL configurada para receber as informações desejadas.
Siga as instruções na tela Tokens & Webhooks:
1. Clique na opção Criar novo webhook.
2. Preencha as informações a seguir:
| Campo | Descrição |
|---|---|
| URL | Informe a URL válida para onde as notificações automáticas serão enviadas. |
| Status | Escolha entre Ativa ou Inativa - apenas webhooks ativos recebem eventos. |
| Versão | Indica a iteração da estrutura do webhook (usada para atualizações e compatibilidade). |
| Tipo de evento | Selecione o tipo de evento que deseja receber (detalhado abaixo). |
| Canal | Disponível apenas para tipos de evento que utilizam canal. |
| Cabeçalhos | Adicione pares Chave: Valor, como Content-Type: application/json. Use conforme as exigências de autenticação do destino. |
3. Se preferir, você pode salvar o Webhook imediatamente após preencher as informações básicas, sem configurar autenticação OAuth2. A configuração de OAuth2 é opcional e pode ser feita posteriormente para adicionar maior segurança ao recebimento dos eventos.
Tipos de eventos disponíveis
Os webhooks podem ser configurados para diferentes tipos de evento, de acordo com o contexto desejado.
| Tipo de evento | Descrição |
|---|---|
| Mensagem | Notifica o conteúdo das mensagens enviadas ou recebidas. |
| Status da mensagem | Envia atualizações sobre o status da mensagem, como envio, entrega ou leitura. |
| Conversa | Notifica eventos relacionados ao início, atualização ou encerramento de conversas. |
| Mensagem da conversa | Envia notificações sobre mensagens trocadas dentro de conversas específicas. |
| Agente especialista de suporte | Notifica execuções de agentes especialistas de suporte configurados com a ação Webhook. Esse tipo de evento é utilizado quando um agente especialista de suporte é executado e tem como ação o envio de um webhook para uma URL específica. Como funciona:
Para entender como configurar e utilizar essa ação, consulte os artigos sobre Agentes especialistas de suporte: o que são e como criá-los e Ações dos agentes especialistas de suporte. |
| Contato | Notifica eventos relacionados à criação e atualização de contatos no Zenvia Customer Cloud. Esses eventos permitem manter os dados de contatos sincronizados com sistemas externos, incluindo informações sobre a origem do contato. Ao configurar esse tipo de evento, é possível definir critérios adicionais, como: 1. Origem do contato: identifica de onde o contato foi criado (por exemplo, integrações ou canais). 2. Ação do contato: define quais ações devem disparar o webhook, como criação ou atualização. Essas informações ajudam a manter os dados de contatos consistentes entre o Zenvia Customer Cloud e sistemas externos integrados. |
Webhooks com OAuth2
Para garantir maior segurança no envio das notificações, use a autenticação OAuth2. Com ela, a Zenvia obtém automaticamente um token de acesso válido antes de enviar cada webhook, protegendo seu sistema contra acessos não autorizados.
- Ao criar ou editar um Webhook, habilite a opção Autenticação OAuth.
- Preencha os seguintes campos de autenticação:
- URL de autenticação: Indique a URL onde será feita a requisição OAuth2 para obter o token de acesso.
- Cabeçalhos (headers): Adicione pares de chave e valor a serem enviados na requisição de autenticação, se necessário (ex: Content-Type: application/json).
- Parâmetros de URL (query params): Caso a autenticação exija parâmetros adicionais na URL, informe os valores nos campos de chave e valor.
- Tipo de permissão (grant type): Campo fixo com o valor Client Credentials, usado para autenticação entre sistemas.
- Client ID e Client Secret: Dados fornecidos pelo serviço autenticador para validar sua integração.
- Refresh token (opcional): Preencha esse campo se a autenticação OAuth2 usar token de renovação.
- Tempo de expiração em segundos (opcional): Defina, se necessário, o tempo de validade do token. Informe um número em segundos (ex: 3600 = 1 hora).
Após preencher os dados de OAuth2, verifique se os campos principais do Webhook já foram configurados (como canal, tipo de evento, URL de entrega e cabeçalhos HTTP). Caso ainda não tenha feito isso, complete essas informações antes de clicar em Salvar.
Caso deseje excluir um Webhook, retorne à tela Tokens & Webhooks e clique na opção Excluir.
Pronto! Com o Webhook configurado com OAuth2, você já pode receber notificações seguras e integrá-las com os canais da Zenvia. Consulte nossa documentação técnica para mais detalhes ou realize testes no Sandbox.
Como funciona o envio de webhooks
Para garantir estabilidade e desempenho, o sistema monitora automaticamente o tempo de resposta das URLs que recebem webhooks. Se houver problemas constantes, a prioridade de envio é reduzida ou os envios podem ser interrompidos.
Regras de funcionamento
- Tempo de resposta: a URL deve responder em até 5 segundos.
- Timeout (sem resposta em 5s) equivale a 10 erros comuns.
- 1 timeout já coloca o webhook em estado degradado, com prioridade reduzida.
- 50 timeouts consecutivos tornam o webhook inativo, e os envios são suspensos.
Boa prática
Responda o webhook o mais rápido possível, mesmo que o processamento da mensagem seja feito depois. Isso ajuda a manter seu webhook com alta prioridade e evita atrasos ou interrupções.