apointoo.
Plataformas de Agendamento

Por que a notificação push do Google Calendar chega sem os detalhes do agendamento?

cmsapointoo··8 min de leitura

A notificação push do Google Calendar chega sem os detalhes do agendamento porque ela sinaliza apenas que o recurso monitorado mudou. O Google envia uma solicitação HTTPS com cabeçalhos X-Goog, mas sem corpo e sem os campos do evento alterado. A integração precisa fazer outra chamada à API para obter a mudança completa.

Esse aviso também não é uma fila permanente. O canal expira, os números de mensagem crescem sem serem sequenciais e o Google alerta que uma pequena parcela das notificações pode ser descartada. O método events.watch usa 604800 segundos como TTL padrão. A aplicação precisa renovar o canal e manter uma rotina de sincronização recuperável.

O que a notificação push realmente informa?

A documentação do Google diz que as mensagens para o URL receptor não incluem corpo. Elas também não informam qual evento foi criado, alterado ou excluído. O POST é um sinal para consultar o recurso monitorado por outro caminho autorizado.

Os cabeçalhos sempre presentes incluem identificador do canal, número da mensagem, identificador e URI do recurso, além do estado do recurso. O estado pode indicar início da sincronização, existência de mudança ou ausência do recurso. Mesmo assim, ele não substitui a leitura do evento.

Trate a notificação como um disparador pequeno. Valide o canal, registre o recebimento técnico e coloque uma tarefa de sincronização na fila. A tarefa consulta o calendário com a credencial e o escopo corretos, aplica as mudanças e registra a conclusão.

Esse desenho é diferente de publicar disponibilidade entre sistemas. O artigo sobre o link da Doctoralia no Google e a agenda do Feegow explica por que um link de agendamento não cria sincronização com o Google Calendar. Aqui, o problema é o envelope de notificação e o ciclo do canal, não a origem da disponibilidade.

Por que os detalhes do agendamento não devem ser inferidos?

Um estado exists informa que houve mudança na coleção monitorada. Segundo o Google, a mudança pode envolver criação, modificação ou exclusão. Sem buscar o recurso, a aplicação não sabe qual dessas ações ocorreu nem qual evento foi afetado.

Não use o último evento visto, o horário atual ou o número da mensagem para preencher essa lacuna. Essas pistas não identificam o registro alterado. Uma inferência errada pode remover um bloqueio válido, duplicar um evento ou associar uma mudança ao agendamento incorreto.

Inferência operacional: mantenha a atualização em estado pendente até que a consulta autorizada confirme o conteúdo. Se a agenda participa da publicação de horários, não interprete uma notificação sem leitura concluída como prova de que o horário ficou livre.

A origem de marketing também não vem no webhook. Mesmo quando um evento corresponde a uma consulta, preserve separadamente a origem do agendamento e a origem de marketing. Um aviso técnico do Google Calendar não deve substituir nenhuma delas.

Quais cabeçalhos precisam ser preservados?

O receptor precisa correlacionar X-Goog-Channel-ID com um canal criado pela própria aplicação. X-Goog-Resource-ID identifica de forma opaca o recurso monitorado, enquanto X-Goog-Resource-URI representa seu endereço específico da versão da API. Preserve essa relação no registro interno do canal.

O X-Goog-Channel-Token aparece quando a aplicação definiu um token na criação. O Google recomenda usá-lo para verificar que a mensagem pertence a um canal criado pelo sistema e orienta a não colocar dados sensíveis nesse valor. Use um identificador opaco, sem nome, contato, motivo de consulta ou conteúdo clínico.

O cabeçalho de expiração aparece quando o canal tem prazo definido. Ele serve para programar a substituição antes do fim, não para descobrir a expiração depois que as mensagens pararam. Guarde também o horário em milissegundos devolvido pela resposta de watch.

Registros gerais devem conter somente metadados técnicos: canal, recurso, estado, número da mensagem, horário de recebimento e resultado da sincronização. Não copie descrição, convidados ou anotações do evento para provar que o webhook chegou.

Os números de mensagem revelam notificações perdidas?

Não como uma sequência contínua. O Google informa que mensagens sync usam o número 1. As mensagens seguintes têm números maiores, porém não sequenciais. Um salto não prova quantos avisos faltaram e não deve produzir eventos artificiais.

O valor ainda ajuda a rejeitar regressões óbvias dentro do mesmo canal e a correlacionar recebimentos. Ele não substitui uma sincronização baseada no estado atual da API. Também não deve ser comparado entre canais diferentes, pois cada renovação usa um identificador próprio.

O guia do Google avisa que notificações push não são totalmente confiáveis e que uma pequena parcela pode ser descartada em condições normais. A integração precisa continuar sincronizada mesmo sem receber cada aviso. Crie uma verificação periódica ou outra rotina de reconciliação aprovada.

Se a busca posterior falhar, mantenha a atualização pendente e siga o procedimento de recuperação da API. Não trate uma resposta incompleta ou um erro de sincronização como uma agenda vazia.

Como funciona a expiração e renovação do canal?

O método events.watch aceita params.ttl e documenta 604800 segundos como padrão. A resposta inclui o prazo de expiração quando definido. O Google também pode aplicar limites internos, usando o valor mais restritivo entre a solicitação e seus próprios limites.

Não existe renovação automática. Quando o canal se aproxima da expiração, a aplicação deve criar outro com uma propriedade id exclusiva. O Google observa que pode haver um período de sobreposição em que os dois canais do mesmo recurso permanecem ativos.

Inferência operacional: crie o canal novo, confirme sua resposta e só depois encerre o antigo segundo a estratégia aprovada. O receptor precisa aceitar temporariamente ambos sem aplicar a mesma mudança duas vezes. Expirar o canal anterior antes de provar o novo cria uma janela silenciosa.

Cadastre a relação entre usuário autorizado, agenda, canal, recurso, criação e expiração. Se a credencial ou permissão mudar, trate isso como um evento separado. Uma renovação bem-sucedida não prova que a aplicação ainda consegue listar os eventos.

Qual fluxo transforma o aviso em estado confiável?

O caminho seguro separa recebimento de interpretação. Primeiro, o endpoint valida o canal e o token. Em seguida, registra um sinal técnico durável e responde. Um worker consulta as mudanças pela API, aplica o resultado de forma idempotente e avança o estado de sincronização somente após concluir todas as páginas necessárias.

  1. Correlacione o identificador do canal com um registro ativo.
  2. Valide o token do canal quando ele estiver configurado.
  3. Registre estado, recurso, número e horário sem conteúdo de paciente.
  4. Acione a consulta autorizada dos eventos alterados.
  5. Aplique criação, mudança ou exclusão conforme a resposta real.
  6. Marque a sincronização como concluída apenas após todas as etapas.

Faça o processamento tolerar avisos repetidos e sobreposição de canais. A mesma mudança pode provocar trabalho duplicado no receptor sem significar dois agendamentos. Preserve a identidade do evento e o estado atual antes de executar efeitos externos.

Uma remarcação também não deve apagar a origem original. O guia sobre preservar a origem após uma remarcação ajuda a manter atribuição e estado operacional em campos diferentes.

Como testar sem usar dados de pacientes?

Crie uma agenda controlada com eventos sintéticos e títulos neutros. Não inclua nome, telefone, email, motivo de consulta, diagnóstico ou observação clínica. O teste precisa provar o protocolo do canal, não reproduzir uma consulta real.

Crie um canal e registre a resposta de watch. Confirme a mensagem inicial sync, inclusive o caso documentado em que ela pode chegar antes da resposta de criação por causa do tempo de rede. Depois, altere um evento sintético e verifique que o POST chega sem corpo.

Teste uma notificação repetida, um salto no número da mensagem e uma falha temporária na busca posterior. O estado publicado pela aplicação deve permanecer pendente até a leitura completa. Em seguida, simule a sobreposição entre canal antigo e novo para provar idempotência.

Por fim, deixe um canal de teste atingir seu fluxo de expiração controlado. Confirme que o substituto foi criado com novo identificador e que a aplicação continua encontrando mudanças. A taxonomia de resultados de agendamento ajuda a impedir que esses eventos técnicos sejam contados como novas conversões.

Perguntas frequentes

A notificação push do Google Calendar contém o evento alterado?

Não. O Google afirma que as mensagens não incluem corpo nem informações específicas sobre o recurso atualizado. Use os cabeçalhos para identificar o canal e faça outra chamada autorizada à API para obter a mudança.

Um salto no X-Goog-Message-Number prova perda de mensagens?

Não. Os números aumentam, mas o Google diz que não são sequenciais. Um salto não informa quantas notificações faltaram. Confirme o estado pela API e mantenha uma rotina de reconciliação.

O canal events.watch é renovado automaticamente?

Não. O Google orienta criar um novo canal com identificador exclusivo antes da expiração. O TTL padrão documentado para events.watch é 604800 segundos.

Posso colocar o identificador do paciente no token do canal?

Não é necessário e aumenta o risco. O Google recomenda não colocar dados sensíveis no token. Use um valor opaco que permita correlacionar o canal sem expor paciente, consulta ou credencial.

Referências

Leia também

Gostou do conteúdo? Adicione o Apointoo como fonte preferida no Google.