Saltar para o conteúdo principal

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

  1. Crie um endpoint de Webhook e inscreva-o nos tipos de evento.
  2. Armazene o secret retornado do endpoint.
  3. A YCloud envia uma solicitação de evento para o seu endpoint.
  4. Verifique o YCloud-Signature antes de confiar na solicitação.
  5. Retorne uma resposta 2xx prontamente.
  6. Processe o evento de forma idempotente, pois a entrega pode ser repetida.

Solicitação

Crie um endpoint com POST /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.
Os dois tipos de evento de eco contêm um payload padrão em formato de mensagem 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:
No Dashboard, um novo endpoint inicia sem eventos selecionados. Ao selecionar a categoria Messenger , seus eventos disponíveis são selecionados, incluindo edições e reações. Você pode desmarcar eventos individuais em seguida. Assinaturas existentes não incluem automaticamente eventos de edição ou reação adicionados recentemente. Preserve todas as assinaturas de que você ainda precisa ao atualizar um endpoint. Uma edição mantém o mesmo 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 seu secret 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 o url 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:
  1. Ler o corpo bruto da requisição.
  2. Validar o cabeçalho YCloud-Signature com o segredo do endpoint antes de confiar no payload.
  3. Retornar uma resposta de sucesso 2xx prontamente.
  4. Mover o processamento lento para uma fila.
  5. Tornar o processamento de eventos idempotente para que entregas repetidas não dupliquem ações de negócios.
Não faça parse nem modifique o corpo da requisição antes da validação da assinatura. Use exatamente os bytes brutos recebidos pelo seu servidor.

Resposta do receptor

Retorne uma resposta HTTP de sucesso 2xx assim que a assinatura e a requisição forem aceitas. O corpo da resposta pode estar vazio.
Mova o processamento de negócios lento para uma fila. Um tempo limite ou uma resposta diferente de 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.
Exemplo de payload quando os atributos de contato são alterados
Exemplo de payload quando um novo contato é criado
Exemplo de payload quando um contato é excluído
Exemplo de payload quando um cliente cancela a assinatura
Exemplo de payload quando um cliente retoma a assinatura
Exemplo de payload quando um modelo do WhatsApp é arquivado
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.
Exemplo de payload quando uma chamada do WhatsApp é conectada
Exemplo de payload quando uma chamada do WhatsApp é encerrada
Exemplo de payload quando o status de uma chamada do WhatsApp é atualizado
Consulte a Referência de Webhook para ver disparadores de eventos, campos de payload e exemplos.

Alternar o segredo do endpoint

Alterne um segredo se ele for exposto ou como parte da sua política de segurança:
Implante o novo segredo no seu receptor imediatamente após a alternância.
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.
Para obter o código de verificação de assinatura, intervalos de repetição e implementação do receptor, consulte Implementar um receptor de webhook.