Como configurar webhooks no Celetus Pass?
webhook integração credenciamento controle de acesso assinatura celetus pass
No Celetus Pass, abra Webhooks, clique em Novo webhook, escolha o tipo (Credenciamento ou Controle de acesso), informe uma URL https:// e uma chave secreta de 16 a 200 caracteres e clique em Criar webhook. Cada envio leva a assinatura no cabeçalho X-Celetus-Signature. Em Webhooks enviados, veja o status de cada entrega e use Reenviar nas que falharam. Não é o webhook do painel de vendas.
O webhook do Celetus Pass avisa o seu sistema, por uma requisição POST em JSON, a cada credenciamento confirmado ou a cada acesso (entrada ou saída) registrado na portaria. Para criar, abra Webhooks no Pass, clique em Novo webhook, escolha o tipo, informe uma URL que comece com https:// e uma chave secreta de 16 a 200 caracteres e clique em Criar webhook. Cada envio leva a assinatura no cabeçalho X-Celetus-Signature, e o histórico Webhooks enviados mostra o resultado de cada entrega.
Quais avisos o webhook do Pass envia?
Você escolhe um de dois tipos ao criar o webhook:
| Tipo | Quando dispara |
|---|---|
| Credenciamento | A cada credenciamento confirmado na portaria. |
| Controle de acesso | A cada entrada ou saída registrada. |
Para receber os dois, crie um webhook de cada tipo. O tipo não pode ser alterado depois da criação: para mudar, crie outro webhook. Um webhook ativo vale para todos os eventos da sua conta, não só para um evento.
Veja de onde vêm os registros em Como credenciar participantes e controlar a entrada no evento.
Como cadastrar um webhook
Passo a passo
- No Pass, abra Webhooks, em Integrações, no menu lateral. Para entrar como produtor, veja Como preparar e gerenciar um evento no Celetus Pass.
- Clique em Novo webhook.
- Em Tipo de evento, escolha Credenciamento ou Controle de acesso.
- Em URL de destino, informe o endereço do seu sistema que vai receber os avisos. Ele precisa começar com
https://. - Em Chave secreta, informe de 16 a 200 caracteres. É essa chave que assina cada envio.
- Em Campos enviados, marque o que deve ir no corpo de cada aviso (veja abaixo).
- Confira o exemplo em Pré-visualização do disparo e clique em Criar webhook.
O formulário confere os dados antes de salvar:
- Uma URL que não comece com https:// mostra Use uma URL https:// válida.
- Uma chave com menos de 16 caracteres mostra A chave secreta deve ter pelo menos 16 caracteres. Uma chave com mais de 200 caracteres mostra, por exemplo, A chave secreta pode ter no máximo 200 caracteres (agora: 201). Nos dois casos o botão Criar webhook fica desabilitado até você corrigir.
- Endereços internos ou locais (como localhost e redes privadas) são recusados por segurança. Use o endereço público e seguro do seu sistema.
Guarde a chave secreta em um lugar seguro e não a envie por mensagem aberta. Depois de salva, a lista mostra a chave apenas de forma mascarada.
Quais campos o aviso traz?
Todo aviso traz sempre o envelope: event_id, event, evento_id e timestamp. Os demais campos você escolhe em Campos enviados:
| Campo | O que traz | Em qual tipo |
|---|---|---|
| Id da credencial | O identificador do ingresso no Pass, que relaciona o credenciamento e os acessos da mesma pessoa. | Os dois |
| Referência | A referência curta do ingresso. | Os dois |
| Nome | O nome da pessoa. | Os dois |
| CPF/CNPJ | O documento da pessoa. É enviado só se o campo estiver marcado. | Os dois |
| Lote e Área | O lote e a área do ingresso. | Os dois |
| Portão | O portão onde o registro aconteceu. | Os dois |
| Operador | O nome do operador que registrou. | Os dois |
| Direção | ENTRY (entrada) ou EXIT (saída). | Controle de acesso |
| Dia do evento | O dia do evento do acesso, no formato aaaa-mm-dd. | Controle de acesso |
Se você não marcar nenhum campo, o aviso envia os campos do tipo exceto CPF/CNPJ, que exige seleção explícita. Marque só o necessário: o documento é um dado pessoal e só deve seguir se o seu sistema precisar dele. Selecionar todos marca todos os campos, inclusive CPF/CNPJ; Limpar todos desfaz a seleção e volta ao envio padrão, sem CPF/CNPJ.
Como o seu sistema confere a assinatura?
Cada envio chega como POST com Content-Type: application/json e com dois cabeçalhos:
X-Celetus-Event: o tipo do aviso (participant_credentialedpara credenciamento ouaccess_registeredpara controle de acesso).X-Celetus-Signature:sha256=seguido da assinatura HMAC-SHA256 do corpo recebido, calculada com a chave secreta do webhook.
No seu sistema:
Passo a passo
- Calcule o HMAC-SHA256 dos bytes do corpo exatamente como chegaram, usando a chave secreta em UTF-8. Não reserialize o JSON.
- Converta o resultado para hexadecimal minúsculo, acrescente
sha256=no início e compare com o cabeçalhoX-Celetus-Signature. Se não bater, descarte o aviso. - Guarde o
event_ide ignore avisos repetidos: um mesmo aviso pode chegar mais de uma vez, por exemplo depois de um reenvio. - Responda com um código de sucesso (2xx) logo, e processe o resto depois.
Qualquer resposta que não seja de sucesso, ou a falta de resposta, conta como falha da entrega. O Pass não segue redirecionamentos: o endereço cadastrado precisa responder diretamente.
Como acompanhar as entregas
Na própria página Webhooks, o bloco Webhooks enviados traz o histórico de disparos e o status de cada entrega, mais recentes primeiro. Use o campo Status para filtrar.
| Status | O que significa |
|---|---|
| Pendente | O aviso ainda não foi entregue. Se uma tentativa não tiver sucesso, a entrega pode continuar Pendente enquanto o Pass tenta de novo sozinho; Tentativas e Última resposta mostram o que aconteceu. |
| Entregue | O seu sistema respondeu com sucesso. |
| Falhou | A entrega não teve resposta de sucesso e fica parada. Use Reenviar. |
| Descartado | O Pass não tenta mais sozinho: as tentativas acabaram sem sucesso ou o destino estava inativo ou ausente. Confira a Última resposta, corrija a causa e, com o webhook ativo e existente, use Reenviar. |
A tabela mostra Evento, Status, Tentativas, Quando e Última resposta, que ajuda a entender o motivo da falha. Sem nenhum envio, a página mostra Nenhuma entrega registrada ainda.
Como reenviar uma entrega que falhou
Passo a passo
- Corrija o problema no seu sistema (endereço fora do ar, resposta de erro, assinatura recusada).
- Em Webhooks enviados, procure a entrega com status Falhou ou Descartado.
- Clique em Reenviar na linha da entrega.
- Aguarde e confira o novo status na mesma linha.
O botão Reenviar aparece só nas entregas Falhou e Descartado. Ao reenviar, as tentativas voltam a contar do início. Entregas Pendente e Entregue não têm o botão: as pendentes seguem sendo tentadas pelo Pass. Se a entrega não puder ser reenviada, a página avisa Esta entrega não pode ser reenviada. Reenviar uma entrega pode fazer o aviso chegar de novo ao seu sistema, por isso confira o event_id.
O histórico não guarda as entregas para sempre: entregas concluídas ou descartadas saem da lista depois de um tempo.
Como editar, pausar ou excluir um webhook
Cada webhook aparece como um cartão, com o tipo, o número de campos, a URL, a chave mascarada e o selo Ativo ou Inativo.
| Ação | O que faz |
|---|---|
| Chave Ativo / Inativo do cartão | Desativa ou reativa novos avisos sem apagar o cadastro. Entregas já em andamento ainda podem chegar. Entregas pendentes processadas enquanto o webhook está inativo podem ficar Descartado; reativar não as reenvia automaticamente. |
| Editar webhook (lápis) | Muda a URL, os campos e a situação. Em Nova chave secreta (opcional), deixe em branco para manter a chave atual. O tipo não muda. |
| Excluir webhook (lixeira) | Pergunta Excluir webhook? e avisa que o webhook deixará de receber disparos. A ação não pode ser desfeita. |
E se o aviso não chegar?
Confira, nesta ordem:
- O webhook está Ativo?
- Houve credenciamento ou acesso no evento? Sem movimento na portaria, não há aviso. Os registros aparecem em Como acompanhar o evento ao vivo e ver os relatórios do Pass.
- O histórico Webhooks enviados tem a entrega? Leia o Status e a Última resposta.
- O seu sistema valida a assinatura com a mesma chave secreta cadastrada e responde com sucesso, sem redirecionar?
Se o histórico não mostra nenhuma entrega depois de uma passagem na portaria, ou se o problema continuar, fale com o suporte e informe o nome do evento, o tipo do webhook e o horário do registro. Nunca envie a chave secreta. Para o webhook das vendas do painel, veja Meu webhook não foi entregue: o que fazer?. Para saber como o operador registra credenciamentos e acessos, veja Como cadastrar operadores e definir suas funções no evento e Como configurar um evento com ingressos.