Consumo de eventos usando webhooks

O conteúdo desta página se aplica somente a SaaS. Para receber as cargas úteis do evento por meio da chamada POST, o servidor webhook deve executar algumas ações.

As ações são as seguintes:
  • Validar o token fornecido Oauth.
    • Se o token tiver expirado ou for inválido, responda com o código de resposta 40x apropriado.
    • Se o token fornecido for válido, armazene a mensagem de uma maneira que seja improvável a perda de dados. Sugere-se armazenar a mensagem gravando em um tópico Kafka, fila JMS, sistema de arquivos ou banco de dados.
  • Responda à chamada POST com uma mensagem 200 quando os dados forem persistidos de alguma forma.
Se a validação de dados for necessária, é altamente recomendável que o próximo estágio execute qualquer validação necessária, em vez de atrasar uma resposta imediata. Os atrasos de resposta podem ser confundidos com erros de tempo limite que levam à republicação de dados. Isso pode ter um efeito cascata, em que as mensagens são publicadas repetidamente porque o servidor não está respondendo prontamente e torna o tempo de resposta do webhook ainda mais lento.

Ao implementar o servidor de webhook, você precisa prestar muita atenção ao tempo de resposta do webhook. Qualquer solicitação que não receba uma resposta em 5 segundos é considerada falha e é tentada novamente. Se a mensagem repetida continuar a falhar por algum motivo, o sistema considerará isso como falha na entrega do evento e a carga útil será movida para a fila de processamento de eventos com falha.

Se o seu webhook responder com um código de erro indicando que o token expirou (401), tentaremos gerar e usar um novo token, a menos que isso já tenha falhado na geração de um token válido. Nesse caso, encaminharemos o evento para a fila de processamento de eventos com falha.

O sistema reconhece que o servidor Oauth fornecido provavelmente não é dimensionado para receber o mesmo volume de solicitações que o servidor de webhook. Para reduzir o número de chamadas para o servidor Oauth, o sistema tenta atualizar o token Oauth aproximadamente 30 minutos antes da expiração.

Você pode fornecer a duração do token das duas maneiras a seguir:
  • Quando os webhooks estão integrados, você pode fornecer a validade do token em número de horas. Caso a validade mude, atualize o servidor com a nova duração.
  • Você pode incluir a duração do token em segundos no campo expires_in no corpo da resposta Oauth. Isso permite que o sistema calcule quando o token expira cada vez que é gerado e permite que você faça alterações na duração do token.
    Nota: Recomenda-se que os tokens gerados durem no mínimo uma hora.