Webhooks: avise outras ferramentas

#O que é um webhook

Pense nisso como o seu projeto ligando para outro serviço para contar o que acabou de acontecer. Você dá ao Briks um endereço (uma URL fornecida pela outra ferramenta), escolhe os eventos que ele deve avisar, e a cada vez que um acontece o Briks envia uma mensagem para lá. Muitas ferramentas de automação, de lista de clientes e complementos de planilha podem fornecer esse endereço.

Tecnicamente, cada mensagem é uma requisição POST: uma chamada que leva um corpo, aqui escrito em JSON, um formato de texto simples que programas leem. A ferramenta que recebe lê o corpo e faz o que você configurou.

record.changed acompanha as alterações feitas no estúdio: um registro adicionado, editado ou excluído na aba Database, uma coleção esvaziada ou o banco de dados restaurado. Registros que o site no ar salva sozinho, como um pedido de reserva enviado por um visitante, não o disparam.

form.received é enviado tanto para envios feitos na prévia quanto na produção. Cada mensagem informa qual é o caso, para que a outra ferramenta possa ignorar os envios da prévia.

#Limites de cada plano

Quando as chamadas do dia acabam, a entrega não é enviada e fica marcada como Failed com: As chamadas de hoje para este projeto acabaram, então esta entrega não foi enviada. Envie-a de novo amanhã.

Quando um projeto tem tantos webhooks quanto o plano permite, Add webhook fica desativado e um link Get more ao lado da contagem abre a janela de upgrade, que indica o menor plano com espaço para mais um.

#Adicionar um webhook

Cada webhook da lista mostra seu endereço, a nota e os eventos, com qual segredo ele é assinado (os primeiros caracteres) e como foi a última entrega. O interruptor o coloca em On ou Off, e os três pontos reúnem Send a test event (até dez por hora, só enquanto ele está ativo), Change, New signing secret e Delete.

#Como é uma entrega

Toda entrega tem as mesmas três partes: type (o código do evento), timestamp (quando aconteceu, em UTC) e data (os detalhes). Aqui está uma entrada de formulário:

Cada entrega também traz três cabeçalhos: webhook-id (o id da mensagem), webhook-timestamp (quando foi enviada, em segundos) e webhook-signature. Eles seguem o formato aberto Standard Webhooks, então ferramentas que o entendem podem verificar as entregas para você.

#Confira se uma entrega é genuína

Qualquer pessoa pode enviar uma mensagem para um endereço, então quem recebe deve verificar a assinatura antes de confiar nela. A assinatura é feita com o segredo de assinatura que só você e o Briks têm. Quando um projeto tem um webhook, a página Webhooks mostra um pequeno exemplo de código em Checking a delivery is genuine. Em palavras, a verificação funciona assim:

1. Pegue o corpo exatamente como chegou, como texto, antes de lê-lo como JSON.
2. Junte o webhook-id, o webhook-timestamp e o corpo com pontos finais entre eles.
3. Pegue seu segredo, tire o whsec_ do início e decodifique o restante de base64. Essa é a chave.
4. Assine o texto unido com HMAC SHA-256 e essa chave, escreva o resultado em base64 e coloque v1, na frente.
5. A entrega é genuína se isso corresponder a um dos valores separados por espaço em webhook-signature e o carimbo de data e hora estiver a até cinco minutos do momento atual.

Uma entrega que é tentada de novo mantém o mesmo webhook-id, para que o destinatário guarde os ids que já tratou e ignore as repetições.

#Entregas e novas tentativas

Deliveries lista todas as entregas dos últimos trinta dias, da mais recente para a mais antiga. Filtre com Status e clique em Show. Clique em uma para ver a mensagem completa, qualquer erro e o que o endereço respondeu.

Cada tentativa espera até 15 segundos por uma resposta. Se a resposta não for 2xx, Briks tenta de novo: cinco tentativas no total, a primeira na hora e depois após cerca de 30 segundos, 2 minutos, 8 minutos e 32 minutos, ou seja, cerca de 45 minutos da primeira à última. Uma resposta 410 (gone) interrompe as tentativas na hora. Redirecionamentos não são seguidos, então informe o endereço final.

Quando uma entrega fica Failed ou Delivered, Send again envia a mesma mensagem com o mesmo id, assinada de novo. O webhook precisa estar ativado.

#Insights e configurações

Insights resume os últimos trinta dias: Deliveries, a parcela Delivered, Failed after every try (com o número de novas tentativas feitas) e o tempo de Average answer. Abaixo, By event e By address mostram onde as falhas se concentram.

Settings tem Download JSON em Download the webhooks, com o endereço, os eventos e a nota de cada webhook. Os segredos de assinatura nunca são incluídos. A zona de perigo traz Clear log, que apaga o registro de entregas e interrompe novas tentativas, e Delete all, que remove todos os webhooks depois que você digita o nome do projeto. Ambos são para Owners e Admins.

#Exemplo prático: enviar entradas de formulário para outra ferramenta

As entradas de formulário não podem ser exportadas do estúdio, então um webhook é a forma de mantê-las em outra ferramenta assim que chegam. O estúdio também as guarda: as últimas 100 aparecem em Settings, Forms.