osFoundry / Platform
Webhooks de entrada
Uma URL por app ou workspace para receber eventos. Verificação de assinatura embutida.
O que é
Os webhooks de entrada dão ao osFoundry um endereço de recebimento para o mundo externo. Você gera um token com escopo em um app, uma instância e um canal específicos, e o osFoundry devolve uma URL dedicada em /api/v1/webhooks/inbound/{id}. Sistemas externos (Stripe, GitHub, Zapier, um pipeline de CI, seu próprio backend) enviam JSON via POST para essa URL, e o evento chega ao canal em tempo real que você escolheu, onde seu chat, seus agentes e seus apps podem agir sobre ele. Não há polling nem um servidor de integração separado para manter: o endpoint é a integração.\n\nA verificação de assinatura já vem embutida, não acoplada por cima. Cada token carrega um segredo de assinatura HMAC-SHA256, exibido uma única vez no momento da geração. O emissor calcula uma assinatura sobre o payload e a envia no cabeçalho X-OsFoundry-Signature; o osFoundry a valida em cada requisição e rejeita qualquer coisa sem assinatura ou alterada em trânsito. Quando você precisa trocar a chave de um emissor, girar o segredo abre uma janela de tolerância de 7 dias durante a qual o segredo anterior continua válido, de modo que a rotação nunca descarta um evento em andamento. Revogar um token é imediato: o endpoint passa a devolver 401 na hora, o que é o caminho rápido para um segredo vazado ou uma integração desativada.\n\nComo isso roda dentro do espaço de trabalho desktop BYOK do osFoundry, um evento de entrada pode acionar os mesmos agentes, apps e conhecimento com que você já trabalha, sem taxa de integração por assento nem desvio dos seus dados por um intermediário terceiro. Cada token registra sua última hora de uso e a contagem de requisições das últimas 24 horas, para você ver quais emissores estão ativos, e a plataforma retém as últimas 100 requisições de entrada para reenvio, o que transforma a depuração de webhooks de adivinhação em reexecutar o payload real.
Principais recursos
- Gere uma URL de recebimento dedicada por app, instância e canal: sistemas externos enviam eventos JSON via POST direto para esse endpoint em /api/v1/webhooks/inbound/{id}
- Cada requisição é verificada contra uma assinatura HMAC-SHA256 no cabeçalho X-OsFoundry-Signature, então payloads sem assinatura ou adulterados são rejeitados antes de chegar ao seu canal
- Gire um segredo de assinatura com uma janela de tolerância de 7 dias na qual o segredo antigo ainda valida, para trocar a chave dos emissores sem perder eventos
- Revogue um token na hora: o endpoint devolve 401 no momento da revogação, cortando um emissor vazado ou aposentado
- Veja o horário do último uso e a contagem de requisições de 24 horas por token, e reenvie as últimas 100 requisições de entrada pelas configurações do gatilho quando precisar depurar uma entrega
Casos de uso
- Desenvolvedor conectando o Stripe: gera um token com escopo em um canal de faturamento, aponta o webhook do Stripe para a URL e deixa o osFoundry rejeitar qualquer POST cuja assinatura HMAC não bata antes de chegar a um agente
- Engenheiro de operações com um segredo vazado: revoga o token afetado para um 401 imediato e gera um novo, sem derrubar as outras integrações que alimentam o espaço de trabalho
- Construtor de automações conectando um pipeline de CI: envia eventos de status de build via POST para um canal onde um agente triagem as falhas, usando o reenvio das últimas 100 requisições para depurar o formato do payload
Perguntas frequentes
Como o osFoundry verifica que um webhook de entrada é genuíno?
Cada token de entrada tem um segredo de assinatura HMAC-SHA256. O emissor calcula uma assinatura sobre o corpo da requisição e a envia no cabeçalho X-OsFoundry-Signature, e o osFoundry recalcula e compara em cada requisição. Requisições com assinatura ausente ou inválida são rejeitadas, então só um sistema que detém o segredo pode publicar no seu canal. O segredo é exibido uma única vez na geração: guarde-o nesse momento, porque ele não é mostrado novamente depois.
O que acontece com os eventos em andamento quando eu giro ou revogo um token?
A rotação dá uma janela de tolerância de 7 dias na qual tanto o segredo novo quanto o anterior validam, então você pode atualizar cada emissor sem perder eventos durante a troca. A revogação é o oposto por design: o endpoint devolve 401 imediatamente, cortando o emissor na hora, que é o que você quer se um segredo vaza ou uma integração é aposentada.
Recebo uma única URL de webhook para tudo, ou dá para definir escopo?
Cada token tem escopo em um app, uma instância e um canal específicos, e gera sua própria URL em /api/v1/webhooks/inbound/{id}. Isso significa que um emissor não pode publicar em um canal ao qual não teve acesso, e você pode revogar ou girar uma única integração sem mexer nas outras. Cada token também informa o horário do último uso e a contagem de requisições de 24 horas, para você saber quais endpoints estão de fato recebendo tráfego.