Boas práticas no uso de webhooks

O guia a seguir descreve algumas boas práticas recomendadas ao se trabalhar com webhooks.

Responda rapidamente

Depois de receber um evento, é importante responder a request com 202 Accepted dentro de um a dois segundos. Há um tempo limite de cinco segundos para a execução de toda a request antes de ela expirar. Recomendamos utilizar um mecanismo de fila para receber o evento sem necessariamente procesá-lo durante a request do webhook. Isso reduz a chance da request atingir o tempo limite e a entrega do evento ser considerada uma falha. Armazenar o evento em uma fila e responder imediatamente também faz com que seu sistema seja resiliente a um grande volume de solicitações.

Valide o header usando o byte array do body

Como a tecnologia (ou mesmo bibloteca) que usamos para gerar o header de validação deve ser diferente da sua integração, é possível que haja alguma diferença no processo de marshal/unmarshal (parse/stringify, json.loads/json.dumps ou como quer que sua tecnologia chame) do body da request que acabe alterando os bytes da request. Também é possível que novos valores sejam introduzidos nos eventos e que no processo de marshal/unmarshal algum campo não seja tratado e consequentemente não seja levado em consideração na validação da assinatura. Por isso é importante utilizar os bytes do body "as-is" sem nenhuma transformação. É comum que web servers tenham configurações para fazer um parser automático do body, mas que deve ser evitado para essa validação. Utilize o buffer ou byte array da request para essa validação.

Gerenciar atrasos

Em raras circunstâncias, pode haver um atraso na entrega de eventos. Se o recebimento de eventos com até alguns dias de atraso puder causar problemas em seu aplicativo, recomendamos comparar o carimbo de data/hora do evento com a data e hora atuais.

Ignorar eventos duplicados

Embora o serviço de webhook seja projetado para minimizar eventos duplicados, ainda é possível receber o mesmo evento mais de uma vez. Seu aplicativo deve lidar com eventos usando operações idempotentes; isto é, receber o mesmo evento mais de uma vez não deve ter efeito adicional. Você pode detectar eventos duplicados através do campo id do evento.

Rastrear falhas

Use métricas de entrega/código de resposta das requests para rastrear quaisquer falhas nas entregas de eventos e corrigi-las antes que afetem os usuários.

Buscar eventos descartados e rotinas de reconciliação

Se seu aplicativo ficar indisponível por um longo período de tempo, você poderá buscar eventos das últimas 8h no endpoint de polling, seguindo as recomendações do endpoint (utilizando o endpoint de acknowledgment). Se achar interessante, você pode manter o polling em paralelo ao webhook para essa rotina de reconciliação (ou fallback), realizando o polling com uma frequência menor que 30s, por exemplo a cada 30min para rotinas de reconciliação, e reduzir a frequência durante períodos de uso do polling como fallback.