Configurar webhooks

Com uma chave de API, outro programa obtém os seus dados quando precisa deles. Com um webhook, é ao contrário: enviamos uma mensagem para um endereço seu assim que algo acontece.

Isso poupa tempo de espera. Uma encomenda que chega às oito e um quarto está às oito e um quarto na sua contabilidade — e não na ronda seguinte, uma hora depois.

Para que é que os clientes usam isto:

• cada venda de imediato na contabilidade ou numa base de dados própria;
• um pequeno ecrã à entrada que mostra quem acabou de entrar;
• uma mensagem num chat de grupo assim que uma visita guiada esgota;
• um e-mail ou SMS próprio para o comprador, além do nosso.

Este artigo é o manual do ecrã, passo a passo. Se quiser saber primeiro o que é um webhook e se precisa de um, leia Webhooks: saber de imediato que foi vendido um bilhete.

Bom saber: os webhooks fazem parte do mesmo plano que a API. Se estiver num plano inferior, Acesso à API não aparece no seu menu; se mesmo assim chegar a esse ecrã, vê uma explicação e um botão Ir para Assinatura.

Onde tem de ir

No menu à esquerda, abra Definições → Acesso à API e clique no separador Webhooks, no topo. Só a função proprietário vê este ecrã.

Vê três blocos: Nós ligamos-lhe (explicação), Novo destino (o formulário) e Destinos (os que já existem).

O que precisa

Uma coisa, e tem de existir antes de começar: um endereço no seu próprio servidor que possa receber mensagens. Isso exige algum trabalho de programação do seu lado — o seu programador web ou o seu software de contabilidade sabe o que quer dizer quando fala em "um endpoint para webhooks".

Três requisitos:

1. Tem de ser https. Recusamos um endereço http simples: passam dados de compradores por essa ligação.
2. Tem de ser acessível a partir do exterior. Um endereço dentro da rede do seu escritório (algo com 192.168. ou 10.) não o conseguimos alcançar, e também o recusamos.
3. Tem de responder depressa. Esperamos dez segundos. Se o processamento demorar mais, faça o seu servidor responder logo "ok" e só depois continuar a trabalhar.

Adicionar um destino

Passo 1. Preencha o endereço. No primeiro campo (https://...), o endereço completo para onde podemos enviar, por exemplo https://contabilidade.aminhaempresa.pt/webhooks/bilhetes.

Passo 2. Indique para que serve. O segundo campo (Para que serve?) não é obrigatório, mas é útil. "A nossa contabilidade", "ecrã na caixa". Se mais tarde tiver três, sabe logo qual corresponde a quê.

Passo 3. Assinale sobre o que podemos enviar mensagens. Em Sobre o que devemos informá-lo? está a lista. Esta é a escolha mais importante. Assinale apenas o que realmente processa: cada mensagem que não usa é trabalho para o seu servidor e ruído no seu registo. Pelo menos uma caixa tem de estar assinalada; um destino sem mensagens nunca receberia nada.

Mensagem	Quando é enviada
Encomenda criada	Foi criada uma encomenda (um cesto de compras não conta).
Encomenda paga	O dinheiro entrou.
Encomenda cancelada	A encomenda foi cancelada ou expirou.
Encomenda reembolsada	Houve um reembolso total ou parcial.
Bilhete criado	Foi emitido um bilhete.
Bilhete lido	Houve uma leitura à entrada — também quando foi recusada.
Bilhete revogado	Um bilhete foi revogado ou reembolsado.
Horário esgotado	Um horário está cheio.
Horário novamente disponível	Voltou a haver lugar num horário cheio.
Vale-oferta emitido	Foi vendido um vale.
Vale-oferta resgatado	Foi descontado um valor de um vale.
Passe anual emitido	Foi criado um passe anual.
Sessão de caixa fechada	Uma gaveta de caixa foi contada e fechada.
Fatura emitida	Foi emitida uma fatura ou nota de crédito a um comprador.

Passo 4 (opcional). Destino de teste. Se o endereço apontar para um ambiente de teste, assinale Destino de teste (recebe apenas eventos de teste). Mais sobre isto em "Um destino de teste", mais abaixo.

Passo 5. Clique em Adicionar destino.

Pode ter até vinte destinos. Se já tiver vinte, elimine primeiro um.

Só vê o segredo uma vez

Logo a seguir aparece um segredo: uma longa sequência que começa por whsec_.

Copie-o agora e entregue-o a quem constrói a integração. Se atualizar a página ou mudar de separador, desaparece.

Com esse segredo assinamos cada mensagem que enviamos para o seu endereço. O seu servidor pode assim verificar que a mensagem vem mesmo de nós e não de alguém que apanhou o seu endereço algures. Não é um luxo: sem essa verificação, o seu endpoint é uma porta aberta por onde qualquer pessoa pode fazer passar encomendas.

Perdeu o segredo? Clique em Novo segredo. Recebe logo um novo e o antigo deixa de funcionar a partir desse momento — não se esqueça, portanto, de o substituir também do outro lado.

Para quem constrói a integração, o portal para programadores explica exatamente como verificar essa assinatura, com exemplos em PHP, JavaScript e Python. Através da API pode também pedir uma mensagem de exemplo assinada para testar o seu próprio código, sem ter de fazer primeiro uma venda.

Testar sem venda

Clique em Mensagem de teste ao lado de um destino. Enviamos então uma mensagem do tipo test.ping — sem dados reais, apenas um sinal.

Por baixo abre-se logo o registo de mensagens, para que veja o que o seu servidor respondeu. Se aparecer Entregue, funciona. Se aparecer um código de erro, sabe onde procurar. Uma mensagem de teste também é enviada para um destino desativado.

O registo de mensagens

Clique em Mensagens ao lado de um destino. Vê as últimas cinquenta mensagens e, para cada mensagem:

• de que tipo era e quando foi enviada;
• o que o seu servidor devolveu (o número é o estado http; 200 significa "ok");
• quantas vezes tentámos;
• em que ponto está: Entregue, A caminho (ainda estamos a tentar) ou Não entregue.

Se uma mensagem não foi entregue, pode, com Tentar novamente, voltar a enviar a mesma mensagem. Útil depois de resolver uma avaria do seu lado.

As mensagens ficam guardadas durante trinta dias. Depois são eliminadas: o registo serve para encontrar um problema, não como arquivo.

O que acontece se o seu servidor falhar por momentos

Não desistimos logo. Se uma mensagem não chegar, tentamos de novo seis vezes, com intervalos cada vez maiores: ao fim de um minuto, cinco minutos, meia hora, duas horas, doze horas e um dia. No total, mais de um dia e meio.

Se mesmo assim não resultar:

• o destino recebe a etiqueta Sem ligação;
• recebe um e-mail. Esse e-mail vai para o E-mail de contacto da sua organização, ou para o Endereço de faturação (e-mail) se o primeiro estiver vazio (ambos em Definições → Organização, separador Contacto);
• o destino continua simplesmente ativo. Os eventos seguintes voltam a ser enviados e, assim que algo volte a chegar, a etiqueta desaparece.

Recebe no máximo um e-mail destes por dia e por destino. Um servidor em baixo durante um fim de semana não origina, portanto, cem e-mails.

Um destino de teste

Ao criar, assinale Destino de teste quando o endereço apontar para um ambiente de teste. Um destino destes recebe apenas eventos de teste — o que acontece com as encomendas de teste de uma chave de teste — e nunca vendas reais. Na lista tem a etiqueta Teste. Inversamente, um destino normal nunca recebe nada de uma encomenda de teste.

Esta separação é rígida, e propositadamente: um servidor de teste que processe por engano uma encomenda real envia uma confirmação a um comprador real.

Desligar ou eliminar

Desligar para as entregas, mas mantém o destino, com o seu segredo e o seu registo de mensagens; recebe a etiqueta Desligado. Útil durante uma manutenção do seu lado. Clique novamente em Ligar e volta a funcionar.

Eliminar remove o destino e o seu registo de mensagens. Isto não pode ser anulado; um novo destino recebe um novo segredo.

Há ainda um terceiro caso: se o seu servidor alguma vez responder com o código 410, desativamos nós próprios o destino. Esse código significa literalmente "este endereço já não existe", e continuar a bater à porta seria indelicado. O mesmo acontece quando, entretanto, o endereço passa a apontar para uma rede interna. Clique em Ligar assim que estiver tudo em ordem.

Três dicas para quem constrói a integração

1. Responda primeiro, processe depois. Responda logo "ok" e faça o trabalho real em segundo plano. Caso contrário, esbarra nos nossos dez segundos.
2. Processe de forma idempotente. Cada mensagem tem um número próprio (a Idempotency-Key). Se o mesmo número chegar duas vezes, não faça nada. Em caso de dúvida voltamos a tentar, e um registo contabilístico em duplicado é pior do que uma linha de registo em duplicado.
3. Não conte com a ordem. Duas mensagens podem ultrapassar-se quando a primeira é repetida. Olhe para a hora na mensagem e para o conteúdo, não para a ordem de chegada.

Para saber mais

• Webhooks: saber de imediato que foi vendido um bilhete — o que é um webhook e quando precisa de um, sem termos técnicos.
• Criar uma chave de API — o outro separador deste ecrã.
• O portal para programadores — para quem faz a integração.