Com os webhooks, a API Apps envia uma notificação em tempo real ao seu aplicativo sempre que um evento relevante ocorre durante uma sessão de chat, por exemplo, quando um chat é criado, uma mensagem é recebida ou um chat é transferido ou encaminhado. Use webhooks para reagir à atividade do chat conforme ela acontece, em vez de pesquisar a API.
Os webhooks são limitados a sessões de chat na API Apps. Contact Center AI Platform entrega todos os eventos de webhook de chat da API de apps compatíveis como solicitações HTTP POST para um único URL de webhook que você configura. Não há uma assinatura por evento.
Antes de começar
- Você precisa ser um administrador ou ter uma função com permissão para editar as configurações do desenvolvedor para configurar webhooks.
- Prepare um endpoint que possa receber solicitações HTTP
POST. O URL do webhook precisa usar HTTPS.
Ativar webhooks
Quando você ativa os webhooks, a Contact Center AI Platform entrega eventos de webhook ao URL configurado, e os campos de URL e secreto aparecem. Quando os webhooks estão desativados, nenhum evento é enviado.
Para ativar webhooks, siga estas etapas:
- No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.
- Acesse o painel Webhooks e clique na opção Webhooks para ativar.
Configurar o URL do webhook
- Em URL, insira o endpoint do webhook.
- Confirme se o endpoint usa HTTPS e pode receber solicitações
POST. A Contact Center AI Platform envia todos os eventos compatíveis para esse único URL.
Gerar chaves secretas de assinatura
A Contact Center AI Platform assina todas as solicitações de webhook para que seu aplicativo possa confirmar que a solicitação veio da plataforma. Ele envia a assinatura no cabeçalho da solicitação X-Signature e o carimbo de data/hora da assinatura em X-Signature-Timestamp.
É possível configurar até dois secrets de assinatura:
- Segredo principal: o token principal usado para assinar solicitações de webhook.
- Secret secundário: um segundo token opcional. Quando um secret secundário é definido, a Contact Center AI Platform assina cada solicitação com os dois secrets, o que permite girar os secrets sem perder eventos.
Gere cada secret separadamente. Para gerar um segredo, siga estas etapas:
- No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.
- Acesse o painel Webhooks.
- Na seção Secret principal, clique em Gerar. Clique em Copiar para copiar um segredo e armazená-lo com segurança. A senha completa só é mostrada logo após a geração. Depois, ela é mascarada.
- Opcional: na seção Secret secundário, clique em Gerar. Clique em Copiar para copiar um segredo e armazená-lo com segurança.
- Confirme na caixa de diálogo de aviso. Um novo secret entra em vigor imediatamente. Portanto, qualquer coisa que ainda use um secret substituído vai falhar.
Alternar secrets de assinatura
Quando um secret principal existe, uma ação Rotacionar secrets fica disponível. A rotação periódica de secrets é uma prática recomendada de segurança. Como a Contact Center AI Platform assina cada solicitação com os segredos principal e secundário, é possível fazer a rotação sem interromper a entrega:
- No portal da plataforma CCAI, clique em Configurações > Configurações do desenvolvedor. Se o menu Configurações não aparecer, clique em Menu.
- Verifique se um secret principal e um secundário estão definidos.
- Clique em Girar secrets para trocar os secrets primário e secundário.
- Atualize seu aplicativo para verificar as assinaturas com o novo secret ativo. Durante a sobreposição, a Contact Center AI Platform assina cada solicitação com os dois segredos configurados. Portanto, aceite qualquer um deles para que a entrega não seja interrompida.
Salvar a configuração
Selecione Salvar para aplicar o estado ativado e o URL do webhook. A geração ou rotação de um secret entra em vigor imediatamente e não requer uma operação de salvamento. A Contact Center AI Platform começa a entregar eventos depois que os webhooks são ativados e um URL do webhook e um segredo principal são definidos.
O que seu aplicativo recebe
Depois que você ativa os webhooks, a Contact Center AI Platform envia uma solicitação HTTP POST para
cada evento de chat compatível, como mudanças no ciclo de vida, atividade do participante,
mensagens, transferências, encaminhamentos, formulários da Web e avisos de dispensa. Cada corpo de solicitação é um envelope JSON com event_type, timestamp, chat_id e um body específico do evento.