Webhooks: saber de imediato que foi vendido um bilhete

Imagine: quer que o contador no seu próprio site se atualize logo que é vendido um bilhete. Há duas maneiras de o conseguir, e uma delas é bastante melhor.

Este artigo explica o que é um webhook e se precisa de um. Como configurar um, botão a botão, está em Configurar webhooks.

O mundo ao contrário

Sem webhook, o seu site tem de estar sempre a perguntar. A cada minuto, o dia inteiro: "já se vendeu alguma coisa?" Quase sempre a resposta é não. Num dia, são mil e quatrocentas perguntas para ouvir três vezes sim — e entre duas perguntas o seu contador está errado.

Com um webhook, inverte-se a situação. Dá-nos um endereço do seu próprio site e, assim que algo acontece, enviamos para lá uma pequena mensagem. Uma mensagem, no próprio momento.

Daí o nome: um hook é um gancho onde penduramos algo quando chega a altura.

O que pode fazer com ele

• atualizar o contador no seu site assim que há uma venda;
• receber uma mensagem no chat da sua equipa em cada encomenda acima de um determinado montante;
• atualizar a sua lista de sócios quando alguém compra um passe anual;
• enviar um e-mail para si próprio quando uma encomenda é cancelada;
• avisar logo a sua caixa ou contabilidade de que entrou dinheiro.

O que precisa

Três coisas, e o seu programador web conhece-as todas:

1. Um endereço no seu próprio site que possa receber mensagens. É uma página normal que ninguém visita; existe apenas para receber a nossa mensagem. Tem de começar por https://.
2. Um sítio para introduzir esse endereço. Faz-se no próprio painel, em Definições → Acesso à API, no separador Webhooks — consulte Configurar webhooks. Se o seu programador web preferir tratar disso a partir do seu próprio programa, precisa de uma chave com a permissão Webhooks; consulte Criar uma chave de API.
3. O segredo associado a esse endereço. Recebe-o de nós assim que o endereço estiver configurado, e com ele o seu site confirma que uma mensagem vem mesmo de nós.

Este terceiro ponto é importante. Sem verificação do segredo, qualquer pessoa que adivinhe o seu endereço pode fazer o seu site acreditar que se vendeu alguma coisa. Com essa verificação, não.

Como funciona na prática

Chega uma pequena mensagem que diz o que aconteceu e a que diz respeito. O seu site verifica o segredo, vê que está correto e depois faz algo com a mensagem: aumentar um contador, registar uma linha, enviar um e-mail.

O que contém exatamente uma mensagem destas, e como programar a verificação do segredo, está no portal para programadores — é a página que reencaminha a quem faz a integração.

Três coisas que correm mal com frequência

Responda depressa. A nossa mensagem espera no máximo dez segundos por uma resposta, não até o seu site terminar todos os cálculos. Aceite a mensagem, confirme que chegou e faça o trabalho depois.

Conte com repetições. Se o seu site esteve momentaneamente inacessível, tentamos novamente — até seis vezes, distribuídas por mais de um dia e meio. Pode, portanto, acontecer que a mesma mensagem chegue duas vezes. Garanta que o seu site lida com isso — a mesma mensagem duas vezes não deve originar duas vezes o mesmo e-mail.

Mantenha o segredo em segredo. Deve ficar nas definições do seu servidor, não em código que acabe no seu site.

Precisa disto?

Não. Um webhook é útil quando algo tem de acontecer de imediato. Se lhe bastar um resumo diário, não precisa de um — basta obter os números uma vez por dia.

Os webhooks fazem parte do mesmo plano que o resto da API. O que está incluído em cada plano está na página de preços de Passavo.

Para saber mais

• Configurar webhooks — o próprio ecrã: adicionar um endereço, enviar uma mensagem de teste, ler o registo de mensagens.
• O que é uma API e preciso dela?
• Criar uma chave de API
• O portal para programadores — para quem faz a integração.