Webhooks
Os artigos de ajuda podem não estar totalmente exatos — devido a atualizações frequentes e tradução automática, podem ficar desatualizados em relação à aplicação. Em caso de dúvida, contacte o suporte.
Um webhook avisa o seu próprio sistema no momento em que algo acontece no EventMann, para não ter de perguntar constantemente. O EventMann envia um pedido HTTPS para um endereço que você escolhe sempre que ocorre um evento subscrito: uma reserva é confirmada, uma encomenda é reembolsada, um evento é publicado. Os webhooks estão no separador Webhooks de Integrações na barra lateral.
- Abra Integrações e clique no separador Webhooks.
- Clique em Adicionar Webhook para criar um endpoint.
- A coluna Estado mostra Ativo ou Desativado, com o código HTTP da última tentativa.
- Um endpoint desativado oferece Reativar.
Adicionar um endpoint
- Dê-lhe um Nome, para uso próprio.
- Introduza o URL do Endpoint, um endereço web público que aceite um POST.
- Marque os eventos que pretende em Subscrever Eventos. É necessário pelo menos um.
- Clique em Adicionar Webhook. É criada para si uma chave secreta de assinatura com 64 caracteres.
Eventos que pode escolher
O formulário lista quinze eventos, e cada um deles é enviado:
| Evento | Enviado quando |
|---|---|
booking.created | Uma encomenda passa a existir: no checkout, nas encomendas gratuitas e nas de pedido de aprovação; na etapa de pagamento, nas pagas. |
booking.confirmed | Uma encomenda é confirmada: paga, gratuita ou introduzida manualmente. |
payment.received | Um pagamento é liquidado. É enviado em conjunto com booking.confirmed, incluindo para encomendas gratuitas. |
booking.cancelled | Uma encomenda é cancelada: pelo comprador, por si ou pela sua equipa, ou pelo apoio da EventMann. cancelled_by indica quem (attendee, organizer ou admin). |
booking.refunded | Uma encomenda é reembolsada na totalidade. |
payment.refunded | Um reembolso é liquidado, incluindo os parciais. Um por reembolso, com o respetivo valor. |
event.created | Um evento é criado, independentemente da forma como foi feito (assistente, cópia, série recorrente). |
event.updated | Os detalhes de um evento são alterados: título, descrição, imagem, datas, local ou morada, ligação online, janela de vendas, visibilidade. changed lista os campos. Uma alteração de estado não é uma atualização; tem eventos próprios. |
event.published | Um evento é publicado. |
event.cancelled | Você cancela um evento. |
ticket.checked_in | Um bilhete é admitido à porta: lido, introduzido manualmente, admitido em massa, sincronizado a partir de um leitor offline ou vendido e admitido na bilheteira. Registar a saída de um bilhete e marcar uma ausência não o enviam, nem a ação em massa Fazer check-in na lista de Encomendas, que marca encomendas inteiras como presentes sem leitura à porta. |
staff.assigned | Alguém passa a ser staff num evento: você aprova a candidatura, ou a pessoa aceita um convite para esse evento. |
staff.checked_in | Um elemento da equipa regista a entrada num turno. |
vendor.assigned | Você atribui um fornecedor a um evento. |
vendor.invoice_submitted | Um fornecedor submete uma fatura por uma atribuição. |
Não existem eventos de pagamento aos organizadores. A Stripe paga as suas vendas de bilhetes diretamente para a sua própria conta, e a EventMann não cria nem vê esses pagamentos.
Como é uma entrega
Cada entrega é um POST com um corpo JSON com esta forma: event (o nome), data (os detalhes), timestamp e delivery_id. Os dados de booking.confirmed incluem o id da encomenda, a referência, o estado, o total, o nome e o email do participante, o id do evento e a hora da confirmação. booking.created acrescenta o título do evento e traz, em vez disso, a hora de criação. payment.received inclui o id da reserva, o valor, o gateway, o id da transação e a hora.
O pedido traz três cabeçalhos: X-Webhook-Event, X-Webhook-Delivery-Id e X-Webhook-Signature. A assinatura é um HMAC-SHA256 do corpo bruto do pedido, em hexadecimal, calculado com a chave secreta de assinatura do seu endpoint. Recalcule-a do seu lado a partir do corpo bruto e compare antes de confiar num payload.
Verificar um endpoint
- Clique em Enviar Teste para enviar um
pingde exemplo para o seu endereço e ver o resultado de imediato. - Eventos subscritos mostra o que o endpoint recebe. Use Editar para alterar o nome, o endereço ou os eventos.
- A Chave Secreta de Assinatura está oculta; clique em Mostrar para a revelar.
- Entregas Recentes lista as últimas tentativas com evento, estado, código HTTP, duração e hora. Ver tudo mostra mais.
Novas tentativas, falhas e desativação automática
- Só uma resposta 2xx conta como entregue. Um redirecionamento ou qualquer outra resposta é uma falha; os redirecionamentos não são seguidos.
- Uma entrega falhada é tentada até cinco vezes, aguardando 10, 30 e depois 60 segundos entre tentativas.
- Quando todas as tentativas de um evento falham, a contagem de falhas do endpoint sobe uma unidade. Dez falhas numa hora suspendem a entrega para esse endpoint durante cinco minutos; as entregas aguardam o fim da suspensão.
- Se a suspensão for acionada, ou se a contagem de falhas ultrapassar dez, o endpoint é desativado e você recebe uma notificação com o seu nome.
- Um endereço que aponte para uma rede privada ou interna é recusado no momento da tentativa de entrega. O teste mostra “Bloqueado”, e uma entrega real desativa o endpoint.
- O histórico de entregas é guardado durante 30 dias.
- Um endpoint desativado mostra Este endpoint está desativado com o motivo.
- Corrija o que estava errado no seu recetor e clique em Reativar. A contagem de falhas é limpa; o endereço e a chave secreta mantêm-se. Alterar o nome ou o endereço não reativa o endpoint.
- Tentar Novamente numa entrega falhada envia esse evento de novo, como uma nova entrega, para os seus endpoints ativos atuais que o subscrevem. Isto inclui os seus outros endpoints, por isso podem recebê-lo duas vezes.
Bom a saber
- O envio de webhooks corre numa fila própria, para que um recetor lento não abrande as reservas nem os emails de bilhetes.
- Desmarcar um evento para-o em silêncio. Não recebe nenhum aviso de que deixou de o receber.
- Se ligar uma ferramenta como o Zapier com um token de API da EventMann, as subscrições que ela criar aparecem aqui também, com o nome do evento.
- Os webhooks enviam o nome e o email do participante de cada encomenda para o seu servidor. Certifique-se de que o endereço é seu e de que pode tratar esses dados.
Resolução de problemas
- As entregas pararam e não vejo nenhum erro — abra o endpoint. Se estiver desativado, corrija o recetor e clique em Reativar.
- A assinatura nunca corresponde — calcule o hash do corpo bruto exato, não de uma cópia recodificada, com a chave secreta da página do endpoint, e compare o texto hexadecimal.
- O teste funciona, mas os eventos reais não chegam — verifique se o evento está marcado neste endpoint e se o que aconteceu corresponde à coluna “Enviado quando” da tabela.
- Recebo o mesmo evento duas vezes — carregou em Tentar Novamente, ou tem dois endpoints a subscrevê-lo. Use o id da entrega para ignorar repetições.