Webhooks

Webhooks permitem notificar um destinatário pré-configurado sobre eventos no portal usando callbacks http/https. Um usuário pode configurar webhooks para que eventos no portal 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 DocSpace.

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

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

Depois de criar e configurar seu endpoint, você pode criar webhooks no DocSpace. 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 (Salas, Documentos).
   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 DocSpace 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 portal.
   • URL de carga útil – um endereço do endpoint para onde o webhook deve ser enviado.
   • Chave secreta – defina uma chave secreta do webhook que permite verificar solicitações enviadas para o URL de carga útil. Insira sua própria chave ou clique em Gerar. Por favor, note: você não pode recuperar sua chave secreta novamente uma vez que ela tenha sido salva. Se você perdeu ou esqueceu essa chave secreta, pode redefini-la, mas todas as integrações usando essa chave 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.
   • Gatilho - 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 portal como Usuários, Grupos, Documentos, Pastas e Salas. 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 DocSpace ou apenas ao gatilho selecionado / vários gatilhos. Você receberá notificações automáticas sobre eventos do DocSpace 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 DocSpace.

Você pode desativar ou reativar o webhook criado usando o interruptor ao lado dele. Use o ícone à direita para alterar as configurações do webhook especificadas durante sua criação, visualizar o histórico do webhook ou excluir o 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.
• Gatilho – o gatilho 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.

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 DocSpace, consulte api.onlyoffice.com.