osFoundry / Platform
Webhook in ingresso
Un URL per app o workspace per ricevere eventi. Verifica della firma integrata.
Che cos’è
I webhook in entrata danno a osFoundry un indirizzo di ricezione aperto verso il mondo esterno. Generi un token limitato a un'app, un'istanza e un canale specifici, e osFoundry ti restituisce un URL dedicato sotto /api/v1/webhooks/inbound/{id}. I sistemi esterni (Stripe, GitHub, Zapier, una pipeline CI, il tuo backend) inviano JSON in POST a quell'URL, e l'evento arriva nel canale in tempo reale che hai scelto, dove chat, agenti e app possono agire su di esso. Niente polling e nessun server di integrazione separato da tenere in piedi: l'endpoint è l'integrazione.\n\nLa verifica della firma è integrata, non aggiunta sopra. Ogni token porta con sé un segreto di firma HMAC-SHA256, mostrato esattamente una volta al momento della generazione. Il mittente calcola una firma sul payload e la passa nell'header X-OsFoundry-Signature; osFoundry la convalida a ogni richiesta e rifiuta qualsiasi cosa non firmata o alterata in transito. Quando devi cambiare la chiave di un mittente, ruotare il segreto apre una finestra di tolleranza di 7 giorni durante la quale il segreto precedente resta valido, così la rotazione non scarta mai un evento in corso. Revocare un token è immediato: l'endpoint inizia a restituire 401 all'istante, la via rapida in caso di segreto trapelato o integrazione dismessa.\n\nPoiché tutto questo gira dentro lo spazio di lavoro desktop BYOK di osFoundry, un evento in entrata può attivare gli stessi agenti, app e conoscenze con cui già lavori, senza tassa di integrazione per postazione e senza far deviare i tuoi dati attraverso un intermediario terzo. Ogni token registra l'ora dell'ultimo utilizzo e il conteggio delle richieste nelle ultime 24 ore, così vedi quali mittenti sono attivi, e la piattaforma conserva le ultime 100 richieste in entrata per il replay: il debug dei webhook smette di essere un tirare a indovinare e diventa il rieseguire il payload reale.
Funzionalità principali
- Genera un URL di ricezione dedicato per app, istanza e canale: i sistemi esterni inviano gli eventi JSON in POST direttamente a quell'endpoint sotto /api/v1/webhooks/inbound/{id}
- Ogni richiesta viene verificata rispetto a una firma HMAC-SHA256 nell'header X-OsFoundry-Signature, così i payload non firmati o manomessi vengono rifiutati prima di raggiungere il tuo canale
- Ruota un segreto di firma con una finestra di tolleranza di 7 giorni in cui il vecchio segreto convalida ancora, per cambiare la chiave dei mittenti senza perdere eventi
- Revoca un token all'istante: l'endpoint restituisce 401 nel momento della revoca, tagliando fuori un mittente trapelato o dismesso
- Consulta l'ora dell'ultimo utilizzo e il conteggio delle richieste su 24 ore per ogni token, e riesegui in replay le ultime 100 richieste in entrata dalle impostazioni del trigger quando devi fare il debug di una consegna
Casi d’uso
- Sviluppatore che collega Stripe: genera un token limitato a un canale di fatturazione, punta il webhook di Stripe all'URL e lascia che osFoundry rifiuti qualsiasi POST la cui firma HMAC non corrisponde prima che raggiunga un agente
- Ingegnere ops con un segreto trapelato: revoca il token interessato per un 401 immediato e ne genera uno nuovo, senza far cadere le altre integrazioni che alimentano lo spazio di lavoro
- Creatore di automazioni che collega una pipeline CI: invia in POST gli eventi di stato build in un canale dove un agente smista i fallimenti, usando il replay delle ultime 100 richieste per fare il debug della forma del payload
Domande frequenti
Come verifica osFoundry che un webhook in entrata sia autentico?
Ogni token in entrata ha un segreto di firma HMAC-SHA256. Il mittente calcola una firma sul corpo della richiesta e la invia nell'header X-OsFoundry-Signature, e osFoundry la ricalcola e la confronta a ogni richiesta. Le richieste con firma mancante o non valida vengono rifiutate, così solo un sistema che possiede il segreto può pubblicare nel tuo canale. Il segreto viene mostrato una sola volta alla generazione: salvalo in quel momento, perché in seguito non viene più restituito.
Cosa succede agli eventi in corso quando ruoto o revoco un token?
La rotazione ti dà una finestra di tolleranza di 7 giorni in cui convalidano sia il nuovo sia il precedente segreto, così puoi aggiornare ogni mittente senza perdere eventi durante il passaggio. La revoca è l'opposto per progettazione: l'endpoint restituisce 401 immediatamente, tagliando fuori il mittente all'istante, che è ciò che vuoi se un segreto trapela o un'integrazione viene dismessa.
Ho un unico URL webhook per tutto, o posso limitarne l'ambito?
Ogni token è limitato a un'app, un'istanza e un canale specifici, e genera il proprio URL sotto /api/v1/webhooks/inbound/{id}. Questo significa che un mittente non può pubblicare in un canale a cui non è stato autorizzato, e puoi revocare o ruotare una singola integrazione senza toccare le altre. Ogni token riporta anche l'ora dell'ultimo utilizzo e il conteggio delle richieste su 24 ore, così capisci quali endpoint stanno effettivamente ricevendo traffico.