Webhooks

Introdução

Webhooks permitem notificar um destinatário pré-configurado sobre eventos no espaço de trabalho usando callbacks http/https. Um usuário pode configurar webhooks para que eventos no espaço de trabalho acionem ações em serviços externos. Essa abordagem pode ser útil para sincronizar e rastrear certos eventos.

Use webhooks para realizar ações personalizadas no lado de qualquer aplicativo ou site que você esteja usando com base em vários eventos no ONLYOFFICE Apps.

Você pode criar e gerenciar todos os seus webhooks, configurá-los e navegar pelo histórico de cada webhook para auditar seu desempenho.

Criando um novo webhook

Primeiramente, você precisa configurar um endpoint para webhooks dentro do seu serviço externo. Este endpoint será usado para escutar os webhooks do espaço de trabalho e receber notificações de eventos.

Depois de criar e configurar seu endpoint, você pode criar webhooks no espaço de trabalho. Para criar um novo webhook,

1. Abra a seção Ferramentas do Desenvolvedor clicando no link Ferramentas do Desenvolvedor disponível no painel à esquerda em qualquer seção (Arquivos, Salas, Formulários).

   observação

   Por padrão, o acesso à seção Ferramentas do Desenvolvedor está habilitado para todos os usuários, exceto convidados, para que qualquer usuário possa acessar esta página e, consequentemente, criar seus próprios webhooks. Os administradores podem ver todos os webhooks criados, enquanto os usuários podem ver apenas seus próprios webhooks.

   Os administradores podem tanto usar o link Ferramentas do Desenvolvedor à esquerda quanto alternar para esta seção a partir das Configurações do espaço de trabalho usando o menu no canto inferior esquerdo, selecionando a opção Configurações -> Ferramentas do Desenvolvedor.

2. Na seção Ferramentas do Desenvolvedor, vá para a seção Webhooks.

3. Clique no botão Criar webhook.

4. Defina os parâmetros necessários:

   

   • Nome do webhook – um nome identificador para trabalho conveniente com o webhook no espaço de trabalho.

   • URL de carga útil – um endereço do endpoint para onde o webhook deve ser enviado.

   • Chave secreta – defina um segredo do webhook que permite verificar as solicitações enviadas ao URL de carga útil. Insira sua própria chave ou clique em Gerar. Observe: você não pode recuperar sua chave secreta depois de salva. Se você perdeu ou esqueceu esta chave secreta, abra as configurações do webhook e clique no link Redefinir chave para gerar uma nova. Todas as integrações que usam o segredo anterior precisarão ser atualizadas.

     

   • Verificação SSL – por padrão, esta opção está habilitada para verificar certificados SSL ao entregar cargas úteis. Não é recomendado desativar este parâmetro.

   • Evento para acionar este webhook - use a opção Enviar tudo ou marque o botão de rádio Eventos individuais e escolha apenas os gatilhos certos, ou seja, eventos em alterações de entidades do espaço de trabalho como Usuários, Grupos, Arquivos, Pastas, Salas, Formulários e Agentes de IA. Por exemplo, usuário criado, convidado, atualizado, excluído, etc.

   • ID de destino - um identificador de um usuário, grupo, arquivo ou pasta que permite rastrear alterações de um objeto.

   

5. O URL de carga útil deve responder com status 200 a uma solicitação http com o método HEAD.

6. Clique no botão Criar.

Dependendo das configurações, o webhook criado será atribuído a todos os eventos do espaço de trabalho ou apenas ao gatilho selecionado/vários gatilhos. Você receberá notificações automáticas sobre eventos do espaço de trabalho dentro do seu serviço externo. Gatilhos selecionados durante a criação para um webhook específico são acionados apenas se o proprietário do webhook tiver direitos de acesso à entidade modificada do espaço de trabalho.

Gerenciando webhooks

Os webhooks criados são listados com nome, autor, URL de carga útil e estado. Você pode desativar ou reativar um webhook usando o interruptor na coluna Estado. Use o ícone à direita para abrir o menu de contexto com as seguintes opções:

• Configurações - altere as configurações do webhook especificadas durante sua criação.
• Histórico do webhook - visualize o histórico de entregas do webhook.
• Excluir webhook - exclua o webhook.

Clique no webhook para visualizar o histórico do webhook

Ao visualizar o histórico, você pode filtrar webhooks por data de entrega ou status (Não enviado, 2XX, 3XX, 4XX, 5XX). Clique no botão de filtro , escolha os parâmetros necessários e clique em Aplicar.

Você pode selecionar um ou mais webhooks na lista e usar a opção Repetir que aparece no topo para reenviar os webhooks selecionados. Ou clique no ícone ao lado do webhook específico e selecione a opção Repetir no menu de contexto.

Clique no ícone ao lado do webhook específico e selecione a opção Detalhes do webhook no menu de contexto.

Os seguintes detalhes estão disponíveis:

• Status – um status de resposta.
• ID do evento – um ID do evento.
• Tipo de evento – o evento que causou a ativação do webhook.
• Hora do evento – uma data quando o evento ocorreu.
• Hora da entrega – uma data quando a resposta foi recebida do endpoint.

Nas seções Requisição/Resposta, você também pode visualizar o cabeçalho da requisição POST, o corpo da requisição POST, o cabeçalho da resposta POST e o corpo da resposta POST. Use o ícone para copiar o cabeçalho/corpo da requisição ou resposta para a área de transferência.

Use o ícone ao lado da legenda Detalhes do webhook para reenviar o webhook.

Detalhes técnicos

Os seguintes dois serviços são usados para o trabalho:

1. ASC.Web.Studio fornece métodos para enviar webhooks, lança WorkerService.

   WorkerService – assina para receber mensagens de um broker (por exemplo, RabbitMQ é usado por padrão), que armazena informações sobre novos webhooks aguardando para serem enviados. Mensagens recebidas do broker são colocadas em uma fila, após isso a fila é constantemente consultada e contata de forma assíncrona o ASC.Webhoks.Service para enviar webhooks.

2. ASC.Webhooks.Core fornece métodos para publicar webhooks no banco de dados e no broker de mensagens, bem como métodos para trabalhar com o banco de dados.

Para mais detalhes sobre a API do ONLYOFFICE Apps, consulte api.onlyoffice.com.