Configurar webhooks da empresa

Objetivo

Configurar o recurso Webhooks para receber notificações quando um ou mais recursos do API Procore forem alterados no nível de empresa.

Fundo

O recurso Webhooks permite que terceiro desenvolvedores e integradores especifiquem um ou mais recursos do API Procore para os quais desejam ser notificados quando houver ações das áreas Criar, Atualizar ou Excluir. A interface do usuário para configurar o recurso Webhooks está disponível por meio da ferramenta Administrador da empresa no Procore.

Os benefícios do recurso Webhooks incluem:

Remoção da necessidade de lógica/código de sondagem em integrações de terceiros para determinar alterações de recursos
Aprimoramento do desempenho ao substituir a sondagem por atualizações assíncronas
Maior eficiência, pois só é necessário executar o código mediante a alteração de um recurso
Redução do risco de ultrapassar os limites de taxa da API do Procore

Coisas a considerar

Permissões de usuário necessárias:
- Permissão de nível “Administrador” na ferramenta Administrador de nível de empresa.
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.

Passos

Acesse a ferramenta Administrador de nível de empresa.
Em "Definições da empresa", clique em Webhooks.
Isso abrirá a página de configuração "Webhooks" que inclui um campo Endpoint de notificação para inserir um URL de servidor Web e uma Grade de recursos para selecionar os recursos e as ações de alteração correspondentes para as quais você deseja receber notificação.

Faça o seguinte:
1. Endpoint de notificação. Insira o URL para o endpoint em seu servidor Web que lidará com as solicitações POST provenientes do Procore.
2. Cabeçalho de autorização. (Opcional) Insira o token de autorização que deseja colocar no cabeçalho de uma solicitação POST proveniente do Procore. Embora seja possível usar esse campo para definir qualquer informação de cabeçalho de autorização que você quiser, ele costuma ser mais usado para especificar credenciais de autorização usando a sintaxe: Onde é o tipo de autorização ("Basic", "Token", "Bearer" etc.) e é o valor do token. Por exemplo, uma entrada válida para esse campo seria Basic c3a24b8208ac5199d083d54a1234e94b8864.
3. Salvar endpoint. Clique neste botão para salvar o endpoint. Se você tiver inserido um endereço válido e bem formatado no campo Endpoint de notificação, um banner VERDE aparecerá na parte superior da página indicando o sucesso da operação. Se houver algum problema com a URL você inseriu, um banner de aviso será exibido descrevendo o provável problema.
Na Grade de recursos, marque as caixas "Criar", "Atualizar" e "Excluir" para todos os recursos para os quais deseja receber as notificações correspondentes. Observe que suas seleções de ação entrem em vigor imediatamente conforme você as faz, não havendo necessidade de "enviar" suas alterações.
Obs.: lembre-se de que, ao configurar webhooks, você está apenas identificando sobre quais recursos/ações deseja receber notificações. Você só receberá uma notificação quando houver uma alteração real em um recurso.

Entregas de webhooks

Um registro em execução das Entregas de webhooks para seu endpoint de notificação está disponível na parte inferior da página Webhooks da empresa. A seção Entregas permite ver rapidamente o status dos eventos que o Procore enviou (ou tentou enviar) ao seu servidor de notificação. Entregas bem-sucedidas e malseradas são incluídas na exibição por padrão. Você pode usar a caixa de verificação Mostrar apenas falhas para filtrar a exibição e exibir apenas as entregas com falha.

As entregas mais recentes aparecem no topo da seção Entregas. Ao clicar em uma entrada de entrega, você exibirá detalhes sobre a carga útil da solicitação, os cabeçalhos de resposta e o corpo da resposta.

A exibição do registro de entregas é paginada com no máximo 25 entregas exibidas por vez. Clique em Mais entregas para exibir o próximo conjunto de 25 entregas.

Monitoramento e alarmes

Recomendamos fortemente que você configure o monitoramento adequado de seus servidores de endpoint de notificação para garantir a identificação de qualquer tempo de inatividade ou de outros problemas relacionados ao desempenho e que você seja notificado em tempo hábil por meio de um sistema de alarme confiável. Há muitos sistemas comerciais de monitoramento disponíveis para atender a essa finalidade, incluindo Datadog, New Relic e outros. Esses serviços fornecem recursos robustos de monitoramento que permitem visualizar facilmente a integridade do seu sistema por meio de tabelas, gráficos e análises configuráveis e em tempo real. Esses serviços também fornecem alertas integrados para que você seja imediatamente notificado quando houver problemas.

Veja também

Para obter informações sobre como configurar Webhooks no nível do projeto, consulte Configurar Webhooks do projeto.