O que é
Webhooks são solicitações HTTPS que a YCloud envia para seu aplicativo quando a entrega de mensagens, mensagens recebidas, contatos, modelos, chamadas e outros recursos mudam.Antes de começar
- Armazene sua chave de API da YCloud em
YCLOUD_API_KEY. - Implante um endpoint HTTPS acessível publicamente.
- Preserve o corpo bruto da solicitação para a verificação de assinatura.
- Decida quais tipos de evento seu aplicativo precisa.
Como funciona
- Crie um endpoint de Webhook e inscreva-o nos tipos de evento.
- Armazene o
secretretornado do endpoint. - A YCloud envia uma solicitação de evento para o seu endpoint.
- Verifique o
YCloud-Signatureantes de confiar na solicitação. - Retorne uma resposta
2xxprontamente. - Processe o evento de forma idempotente, pois a entrega pode ser repetida.
Solicitação
Crie um endpoint comPOST /webhookEndpoints.
Campos da solicitação
Exemplo de solicitação
Assinar eventos de eco e transferência
Para Agents integrados por meio da API REST pública, crie um endpoint com as seguintes assinaturas. Agents criados no Console não emitem esses três eventos. Para alterar um endpoint existente, preserve quaisquer assinaturas de eventos de que você ainda precise.whatsappMessage. O evento de transferência contém whatsappMetaBusinessAgent e mantém suas informações de Agent/controle. Eles não usam o contrato whatsapp.smb.message.echoes do WhatsApp Business App. Consulte os detalhes dos eventos de eco e transferência para definições de campos, exemplos, ordenação e limites de correlação de transferência.
Assinar eventos de mensagens do Messenger
Inclua os nomes dos eventos de que você precisa em
enabledEvents ao criar ou atualizar um endpoint. Por exemplo, inscreva-se em todos os quatro com:
messengerInboundMessage.id e metaMessageId, substitui text.body e adiciona editCount e editTime. Os campos sendTime e createTime da mensagem permanecem inalterados; o createTime do envelope do evento é a hora da edição. Mensagens não editadas omitem os campos de edição. Apenas uma mensagem recebida existente é atualizada. Edições mais antigas são ignoradas; mensagens ausentes e edições históricas não são reconstruídas. Correlacione as atualizações por ID de mensagem e use a contagem cumulativa para evitar aplicar um texto mais antigo sobre uma versão mais recente. Tentativas da origem podem criar outro ID de evento para a mesma edição salva. Veja o exemplo de edição de mensagem recebida.
Eventos de reação contêm pageId, o psid do cliente que reagiu, o metaMessageId de destino e a action (react ou unreact). Os campos opcionais reaction e emoji podem estar ausentes, especialmente para unreact. Uma reação não altera o estado de entrega da mensagem. A mensagem de destino pode ter sido originada fora da API da YCloud, portanto, o evento não requer um registro local de mensagem nem inclui um ID local de mensagem.
O createTime do evento retém o horário da interação de origem. Tentativas de reenvio da entrega do cliente mantêm o id e o payload do evento. O processamento de callback da origem pode produzir outro ID de evento para uma interação repetida; não trate os IDs de evento como identidades de reação ou mensagem. Veja os exemplos de payload de reação para ambas as ações.
Resposta
A resposta retorna o endpoint criado e seusecret de assinatura. Armazene o segredo com segurança. A YCloud o utiliza para gerar assinaturas de Webhook.
Exemplo de resposta
Campos de resposta
Receber eventos
Requisição de evento
O YCloud envia um objeto de evento JSON para ourl configurado. O evento inclui campos comuns como id, type, apiVersion e createTime, além de um payload específico do tipo.
O seu manipulador deve:
- Ler o corpo bruto da requisição.
- Validar o cabeçalho
YCloud-Signaturecom o segredo do endpoint antes de confiar no payload. - Retornar uma resposta de sucesso
2xxprontamente. - Mover o processamento lento para uma fila.
- Tornar o processamento de eventos idempotente para que entregas repetidas não dupliquem ações de negócios.
Resposta do receptor
Retorne uma resposta HTTP de sucesso2xx assim que a assinatura e a requisição forem aceitas. O corpo da resposta pode estar vazio.
2xx pode fazer com que o YCloud tente reenviar o evento; portanto, desduplique pelo id do evento.
Exemplos comuns de payload
Expanda um evento para inspecionar o exemplo completo de payload. Esses exemplos vêm da especificação OpenAPI do webhook. Consulte todos os exemplos de payload de webhook para obter todos os tipos de eventos compatíveis.Evento de atributos de contato alterados
Evento de atributos de contato alterados
Exemplo de payload quando os atributos de contato são alterados
Evento de contato criado
Evento de contato criado
Exemplo de payload quando um novo contato é criado
Evento de contato excluído
Evento de contato excluído
Exemplo de payload quando um contato é excluído
Evento de cliente cancela assinatura
Evento de cliente cancela assinatura
Exemplo de payload quando um cliente cancela a assinatura
Cliente retoma assinatura
Cliente retoma assinatura
Exemplo de payload quando um cliente retoma a assinatura
Evento de modelo do WhatsApp arquivado
Evento de modelo do WhatsApp arquivado
Exemplo de payload quando um modelo do WhatsApp é arquivado
Evento de modelo do WhatsApp desarquivado
Evento de modelo do WhatsApp desarquivado
Exemplo de payload quando um modelo do WhatsApp é desarquivado. O status do modelo é o status atual retornado pela Meta e não representa uma nova análise de aprovação.
Evento de chamada do WhatsApp conectada
Evento de chamada do WhatsApp conectada
Exemplo de payload quando uma chamada do WhatsApp é conectada
Evento de chamada do WhatsApp encerrada
Evento de chamada do WhatsApp encerrada
Exemplo de payload quando uma chamada do WhatsApp é encerrada
Evento de status de chamada do WhatsApp atualizado
Evento de status de chamada do WhatsApp atualizado
Exemplo de payload quando o status de uma chamada do WhatsApp é atualizado
Alternar o segredo do endpoint
Alterne um segredo se ele for exposto ou como parte da sua política de segurança:Um endpoint que falha repetidamente ao receber notificações pode mudar para o status
pending e parar de receber eventos. Monitore falhas de webhook e o status do endpoint.
