Configurar webhooks do projeto

Objetivo

Configurar o recurso Webhooks para receber notificações quando um ou mais recursos da API do Procore forem alterados em um projeto.

Histórico

Um webhook é uma mensagem automatizada, ou uma solicitação HTTP, enviada de um aplicativo para outro em tempo real quando um evento específico ocorre, permitindo atualizações de dados em tempo real sem a necessidade de sondagem constante ou solicitações manuais. Webhooks automatizam o processo de transferência de dados entre aplicativos, eliminando a necessidade de um aplicativo verificar constantemente se há atualizações de outro.

No contexto do Procore, o recurso Webhooks permite que administradores de empresas e projetos habilitem desenvolvedores e integradores de terceiro a assinar notificações de eventos para um ou mais recursos API Procore quando houver ações dos tipos Criar, Atualizar ou Excluir. Por exemplo, uma integração de terceiro RFI pode querer ser notificada sempre que um novo RFI for criado no Procore.

Os benefícios do recurso Webhooks incluem:

• Habilitação da comunicação instantânea entre o Procore e terceiro aplicativos e serviços. Em vez de esperar que um aplicativo solicite informações, os webhooks enviam dados do Procore assim que um evento ocorre. Isso garante que os sistemas estejam sempre atualizados.

• Habilitar a automação de fluxos de trabalho acionando ações em aplicativos terceiro sempre que eventos específicos ocorrerem.

• Ao eliminar a necessidade de sondagens constantes, os webhooks reduzem a carga nos servidores e conservam a largura de banda. Isso resulta em um uso mais eficiente dos recursos.

• A redução do número de solicitações de API por meio da sondagem pode levar a uma economia significativa de custos, especialmente para aplicativos que lidam com grandes volumes de dados.

Fatores a considerar

• Informações do administrador:
  • “Administrador” na ferramenta Administrador dos projetos.
• Informações do desenvolvedor:
  • Consulte os guias Introdução aos webhooks e Como usar a API Webhooks no Portal do desenvolvedor para obter informações sobre como desenvolver seu aplicativo ou integração a fim de oferecer suporte adequado a webhooks.

Criando um novo gancho

1. Acesse a ferramenta Administrador de nível de projeto. 

2. Em "Configurações do projeto", clique em Webhooks.

3. Na página Webhooks, clique em Criar gancho.

Isso abre uma nova página de configuração de gancho que inclui vários campos e controles para configurar um gancho.

4. Configuração do ponto de extremidade:

• URL do ponto de endpoint : insira o URL do endpoint no servidor Web do terceiro que processará as solicitações POST provenientes do Procore quando um webhook for acionado.
• Cabeçalho de autorização (opcional) - insira o token de autorização que deseja inserir no cabeçalho da solicitação POST enviada do Procore. Embora esse campo possa ser usado para definir qualquer informação de cabeçalho de autorização desejada, ele costuma ser mais usado para especificar credenciais de autorização para o servidor terceiro. Por exemplo, uma entrada válida para esse campo pode ser 'Basic c3a24b8208ac5199d083d54a1234e94b8864'.
• Formato de carga útil - Selecione a versão de carga útil da API REST que deseja enviar ao serviço terceiro. Você precisará trabalhar com o desenvolvedor terceiro para entender qual formato de carga útil é preferido. Observe que, uma vez que o gancho é criado, a versão da carga não pode ser alterada. Você precisará excluir e recriar o gancho se precisar alterar a versão da carga útil. Para obter informações adicionais, consulte Webhooks Payload Formats

5. Selecione os eventos a serem enviados:

6. Ver eventos selecionados:

Você pode revisar os eventos de notificação selecionados e remover alguns, se necessário.

Exibindo eventos de webhooks

Depois que um gancho for criado e configurado, você poderá visualizar o status dos eventos que o Procore enviou ao serviço de terceiro.
A seção Visão geral fornece um resumo de alto nível do gancho, incluindo o status do gancho e outras informações relevantes.

A seção Eventos exibe o histórico de eventos do gancho selecionado. O histórico do evento é mantido por um período contínuo de 28 dias.

Cada evento é identificado por seu Nome do Recurso, ID do Recurso, Tipo de Evento, Status do Evento e Carimbo de data/hora em UTC.

Os valores possíveis para Status do Evento são os seguintes:

• Entregue - o evento foi entregue com sucesso ao serviço terceiro.

• Descartado - o evento foi descartado. Nenhuma outra tentativa de entrega será feita.

• Falha - a entrega do evento falhou.

• Enfileirado - o evento foi enfileirado para entrega ao serviço terceiro.

• Tentativa novamente - a entrega do evento está sendo tentada novamente.

Você pode executar várias ações com a lista Eventos:

• Pesquise eventos em um recurso específico por ID de recurso.

• Use o menu suspenso Nome do Recurso para mostrar apenas os eventos do recurso selecionado.

• Use a lista suspensa Status do Evento para mostrar apenas os eventos com o status do evento selecionado.

• Use o botão Filtrar para criar um filtro personalizado na lista de eventos.

• Clique em um evento individual na lista para ver detalhes.

Não deixe de conferir

• Para obter informações sobre como configurar Webhooks no nível de empresa, consulte Configurar webhooks da empresa.
• Há compatibilidade das configurações de webhook com modelos de projeto. Para obter informações adicionais, consulte Configurar um modelo de projeto.