osFoundry / Platform
Webhooks de saída
Despache eventos da plataforma para seus próprios endpoints. Auto-retry, verificação de assinatura.
O que é
Os webhooks de saída permitem que o osFoundry envie eventos para endpoints que você controla. Em vez de ficar consultando por mudanças, você registra uma URL e o osFoundry faz uma requisição HTTP para ela sempre que ocorre um evento relevante no seu espaço de trabalho. Assim, a atividade nas suas áreas de chat, agentes, apps, código, conhecimento e dados vira um sinal sobre o qual os seus próprios sistemas podem agir, sem precisar montar uma integração sob medida para cada uma.
Dentro do osFoundry, os webhooks ficam em Configurações e Segurança porque cruzam uma fronteira de confiança: levam eventos do espaço de trabalho para um receptor que é seu. Cada entrega é assinada, de modo que seu endpoint pode verificar que a requisição realmente veio do osFoundry e não foi adulterada no caminho. Confira a assinatura contra o seu segredo compartilhado antes de confiar no corpo da mensagem. Entregas que falham, porque o endpoint estava fora do ar, lento ou retornou um erro, são repetidas automaticamente em vez de descartadas, então uma interrupção breve do seu lado não perde eventos em silêncio. Como o osFoundry é local-first e usa suas próprias chaves (BYOK), os webhooks são o caminho deliberado e opcional para mover dados para fora: você decide quais endpoints recebem eventos, e as cargas vão apenas para onde você aponta.
O valor prático é o desacoplamento. Seu serviço de notificações, seu sistema de chamados, seu data warehouse ou uma automação interna não precisam viver dentro do osFoundry nem guardar credenciais do osFoundry: basta expor um endpoint HTTPS que verifique uma assinatura e retorne um status de sucesso. A verificação de assinatura mais a nova tentativa automática são o que tornam esse endpoint seguro de confiar e confiável de depender, que é a diferença entre um webhook sobre o qual você constrói um fluxo de trabalho e um que você precisa ficar vigiando.
Principais recursos
- Registre seus próprios endpoints HTTPS e receba os eventos da plataforma no momento em que acontecem, sem manter um laço de polling
- Cada carga é assinada, para que seu receptor possa verificar que a requisição se originou no osFoundry antes de agir sobre ela
- Entregas com falha são repetidas automaticamente, então uma queda a jusante não descarta eventos em silêncio
- Gerenciado em Configurações e Segurança como um caminho de saída opcional, por endpoint e sob seu controle total
- Encaixa no modelo local-first e BYOK: os dados só saem para os endpoints que você indica explicitamente
Casos de uso
- Engenheiro de plataforma: encaminhe eventos do espaço de trabalho para um serviço de automação interno sem lhe dar credenciais do osFoundry nem embuti-lo no app
- Operações/plantão: canalize os eventos para um sistema de alertas ou notificações já existente, para que as pessoas certas saibam da atividade em tempo real
- Time de dados: transmita eventos para um warehouse ou endpoint de ETL, mantendo um registro externo sincronizado com o que acontece no espaço de trabalho
Perguntas frequentes
Como verifico que uma requisição de webhook realmente veio do osFoundry?
Cada entrega é assinada. Seu endpoint recalcula a assinatura sobre o corpo da requisição usando o seu segredo compartilhado e a compara com a assinatura que o osFoundry envia. Se não coincidirem, rejeite a requisição. É isso que impede que um terceiro forje eventos para o seu endpoint.
O que acontece se meu endpoint estiver fora do ar quando um evento dispara?
O osFoundry repete a entrega automaticamente em vez de descartá-la, então uma queda breve ou um deploy do seu lado não fazem você perder eventos. Seu endpoint deve retornar um status de sucesso assim que aceitar a carga.
Usar webhooks envia meus dados para algum lugar controlado pelo osFoundry?
Não. O osFoundry é local-first e BYOK, e os webhooks são de saída para endpoints que você registra. Os eventos vão apenas para as URLs que você configura, e você controla quais endpoints existem. É um caminho opcional para mover eventos específicos para sistemas que já são seus.