Este artigo destina-se a gestores de estúdio que enviam eventos do bsport para outras ferramentas. Aborda a criação, teste, pausa e atualização de webhooks em Definições. Para chaves API, consulte "Gerir as suas chaves API".
Visão geral
Um webhook avisa outra ferramenta quando algo acontece no bsport. Quando um cliente reserva uma aula ou uma fatura é criada, o bsport envia os detalhes para um endereço web à sua escolha. A sua ferramenta de relatórios, CRM ou plataforma de automação pode então reagir de imediato, sem ter de consultar o bsport repetidamente.
Gira todos os seus webhooks numa única página: Definições > Webhooks (listado em Integrações).
A página chama-se Webhooks e APIs e tem dois separadores: Webhooks e API. Este artigo aborda o separador Webhooks.
Os webhooks têm versões:
V2 é a versão atual e a que cria.
V1 e Legacy são versões mais antigas que continuam a enviar eventos até serem substituídas (ver "Webhooks antigos: V1 e Legacy" abaixo).
Quem pode usar: gestores cuja função tenha a permissão Webhook. Peça ao administrador do seu estúdio para a ativar na sua função.
O que pode fazer
Criar um webhook para um evento e um URL de destino.
Editar o evento ou o URL de um webhook.
Enviar um teste para verificar que a sua ferramenta recebe eventos.
Pausar um webhook e retomá-lo mais tarde.
Copiar ou rodar o segredo de assinatura de um webhook.
Substituir webhooks antigos (V1 e Legacy) por webhooks V2.
Filtrar a lista por Todos, Ativos ou Pausados.
Casos de uso comuns
Como enviar novas reservas para outra ferramenta
Vá a Definições > Webhooks e selecione Criar webhook.
Em Evento, procure e escolha
booking.created.Em URL de destino, introduza o endereço da sua ferramenta, por exemplo
https://example.com/webhooks/bsport.Selecione Criar webhook.
O webhook fica ativo de imediato. Crie um webhook por evento: para acompanhar reservas que são alteradas ou eliminadas, adicione booking.updated e booking.deleted.
Como verificar que a sua ferramenta recebe eventos
Selecione o ícone de envio (Testar webhook) na linha do webhook. O bsport envia uma entrega de amostra com dados fictícios para o seu URL e mostra o resultado:
Resultado | O que significa |
Entregue | A sua ferramenta respondeu com um estado de sucesso. |
O recetor respondeu com um erro | A sua ferramenta recebeu a amostra, mas respondeu com um estado de erro. O código de estado é apresentado. |
Sem resposta | O bsport não obteve resposta: a ferramenta excedeu o tempo limite, não foi possível alcançá-la, o URL não aponta para um endereço público, ou o seu certificado foi recusado. |
Se testar demasiadas vezes, o bsport pede-lhe que aguarde um minuto antes do próximo teste.
Como pausar um webhook
Pause um webhook para impedir que o bsport envie o seu evento para a sua ferramenta, sem o eliminar. O seu evento, URL e segredo de assinatura permanecem guardados.
Use esta opção enquanto a sua ferramenta estiver em baixo ou a ser atualizada, ou após substituir um webhook V1 por um V2.
Para pausar, desligue o interrutor Ativo na linha do webhook (num telemóvel, selecione antes Pausar webhook)
Nada é enviado enquanto o webhook estiver pausado.
Para retomar, ligue novamente o interrutor, ou selecione Retomar webhook.
Como proteger a sua ferramenta contra eventos falsos
Cada webhook tem um Segredo de assinatura, apresentado ocultado com os seus últimos 4 caracteres. A sua ferramenta usa-o para verificar que um evento vem realmente do bsport. Selecione o ícone de cópia para copiar o segredo para a sua ferramenta.
Para substituir o segredo, selecione o ícone de rotação (Rodar segredo) e confirme. O segredo atual deixa de funcionar imediatamente, incluindo em novas tentativas. Atualize a sua ferramenta com o novo segredo de imediato.
Como funciona
Configuração. Crie um webhook com um evento e um URL público. Use um endereço que comece por
https://ouhttp://. Endereços locais e privados são recusados.Utilização normal. Sempre que o evento ocorre no bsport, o bsport envia o nome do evento, a sua data e os dados do evento para o seu URL. A lista de eventos e o conteúdo de cada entrega encontram-se na documentação de Webhooks (também disponível no canto superior direito da página).
Alterações. Edite o evento ou o URL com o ícone do lápis (Editar webhook) e depois selecione Guardar alterações.
Pausa ou alteração de segredo. Pause para interromper as entregas. Rode o segredo se achar que foi comprometido.
Eventos que pode escolher
A lista de eventos pode mudar. A documentação de Webhooks está sempre atualizada e descreve cada evento e o que o bsport envia. Consulte-a antes de escolher um evento.
28 eventos distribuídos por 11 recursos. Cada nome de evento tem o recurso, seguido do que aconteceu.
Recurso | Eventos |
Reserva |
|
Aula |
|
Cliente |
|
Professor |
|
Fatura |
|
Marcação |
|
Serviço |
|
Estabelecimento |
|
Passe de aulas |
|
Passe de aulas do cliente |
|
Produto |
|
Comportamentos importantes
Um webhook ativo por evento e URL
O bsport recusa um segundo webhook ativo que envie o mesmo evento para o mesmo URL. Para retomar um webhook pausado que duplicaria um webhook ativo, pause primeiro o webhook ativo.
Webhooks antigos: V1 e Legacy
A sua lista pode mostrar webhooks antigos junto aos webhooks V2. Um banner amarelo conta os webhooks antigos que ainda enviam eventos ("a atualizar"). Estes deixarão de funcionar brevemente, por isso mova cada um deles para V2.
Tipo | Onde aparece | O que pode fazer |
V2 | Tabela Webhooks, Versão V2 | Testar, editar, pausar, copiar ou rodar o segredo. |
V1 | Tabela Webhooks, Versão V1 | Pausar, ou Atualizar para V2. Sem rotação de segredo. |
Legacy | Tabela Webhooks Legacy | Atualizar para V2, ou Desativar. Sem pausa, sem segredo de assinatura. |
Para mover um webhook V1:
Selecione Atualizar para V2 na sua linha. O formulário abre com o evento V2 correspondente e o mesmo URL.
Escolha Qual webhook deve receber eventos?
Pausar V1: o novo webhook V2 passa a receber os eventos.
Manter V1 ativo: o novo webhook V2 começa pausado. Retome-o quando a sua ferramenta estiver pronta.
Selecione Criar webhook.
Para mover um webhook Legacy: selecione Atualizar para V2 e crie o webhook V2. O webhook Legacy continua ativo até selecionar Desativar.
Desativar é definitivo. Elimina o webhook Legacy de forma permanente, e o seu evento deixa de ser enviado. Para voltar a receber esse evento, crie um webhook V2.
Sem substituto V2. Os eventos do plano de faturação não têm um evento V2 correspondente, pelo que Atualizar para V2 está desativado para estes. Consulte o guia de migração de webhooks Legacy e o guia de migração de webhooks V1.
Quem vê o quê
Qualquer pessoa com a permissão Webhook vê o separador Webhooks. O separador API é separado e limitado a Proprietários e Administradores. Consulte "Gerir as suas chaves API".
Perguntas frequentes
Não vejo Definições > Webhooks. Porquê?
A sua função não tem a permissão Webhook. Peça ao administrador do seu estúdio para a adicionar à sua função.
Posso eliminar um webhook V2?
Não. Pause-o em vez disso. Um webhook pausado não envia nada.
Porque é que o meu URL é recusado?
O URL tem de ser público e começar por
https://ouhttp://. Endereços locais e privados, comolocalhost, são recusados.
O teste diz "Sem resposta". O que devo verificar?
Verifique se a sua ferramenta está em funcionamento, se o URL é público e se o seu certificado é válido. Depois, teste novamente.
Posso ver o segredo de assinatura na íntegra?
A tabela mostra apenas os últimos 4 caracteres. Use o ícone de cópia para copiar o segredo completo.
Porque não consigo rodar o segredo de um webhook V1?
A rotação é exclusiva dos webhooks V2. Crie um webhook V2 para obter um segredo rotativo.
Artigos relacionados
Documentação de Webhooks: referência de eventos