osFoundry / Platform
Inbound webhooks
A URL per app or workspace for receiving events. Signature verification baked in.
What it is
Inbound webhooks give osFoundry a receiving address for the outside world. You mint a token scoped to a specific app, instance, and channel, and osFoundry returns a dedicated URL under /api/v1/webhooks/inbound/{id}. External systems — Stripe, GitHub, Zapier, a CI pipeline, your own backend — POST JSON to that URL, and the event lands in the realtime channel you chose, where your chat, agents, and apps can act on it. There's no polling and no separate integration server to run: the endpoint is the integration.\n\nSignature verification is built in, not bolted on. Each token carries an HMAC-SHA256 signing secret, shown exactly once at mint time. Senders compute a signature over the payload and pass it in the X-OsFoundry-Signature header; osFoundry validates it on every request and rejects anything unsigned or altered in transit. When you need to re-key a sender, rotating the secret opens a 7-day grace window during which the previous secret still validates, so rotation never drops an in-flight event. Revoking a token is immediate — the endpoint starts returning 401 at once, which is the fast path for a leaked secret or a decommissioned integration.\n\nBecause this runs inside osFoundry's BYOK desktop workspace, an inbound event can trigger the same agents, apps, and knowledge you already work with — no per-seat integration tax and no data detour through a third-party middleman. Each token tracks its last-used time and 24-hour request count so you can see which senders are live, and the platform retains the last 100 inbound requests for replay, which turns webhook debugging from guesswork into re-running the actual payload.
Key capabilities
- Mint a dedicated receiving URL per app, instance, and channel — external systems POST JSON events straight into that endpoint under /api/v1/webhooks/inbound/{id}
- Every request is verified against an HMAC-SHA256 signature in the X-OsFoundry-Signature header, so unsigned or tampered payloads are rejected before they reach your channel
- Rotate a signing secret with a 7-day grace window where the old secret still validates, so you can re-key senders without dropping events
- Revoke a token instantly — the endpoint returns 401 the moment it's revoked, cutting off a leaked or retired sender
- See last-used timestamps and 24-hour request counts per token, and replay the last 100 inbound requests from the trigger settings when you need to debug a delivery
Use cases
- Developer wiring up Stripe: mint a token scoped to a billing channel, point Stripe's webhook at the URL, and let osFoundry reject any POST whose HMAC signature doesn't match before it reaches an agent
- Ops engineer with a leaked secret: revoke the affected token for an instant 401 and mint a fresh one, without taking down the other integrations feeding the workspace
- Automation builder connecting a CI pipeline: POST build-status events into a channel where an agent triages failures, using replay of the last 100 requests to debug the payload shape
Frequently asked questions
How does osFoundry verify that an inbound webhook is genuine?
Each inbound token has an HMAC-SHA256 signing secret. The sender computes a signature over the request body and sends it in the X-OsFoundry-Signature header, and osFoundry recomputes and compares it on every request. Requests with a missing or invalid signature are rejected, so only a system holding the secret can publish into your channel. The secret is displayed once at mint time — store it then, because it isn't echoed back later.
What happens to in-flight events when I rotate or revoke a token?
Rotation gives you a 7-day grace window where both the new and previous secrets validate, so you can update every sender without losing events during the switch. Revocation is the opposite by design: the endpoint returns 401 immediately, cutting off the sender right away — which is what you want if a secret leaks or an integration is retired.
Do I get one webhook URL for everything, or can I scope them?
Each token is scoped to a specific app, instance, and channel, and mints its own URL under /api/v1/webhooks/inbound/{id}. That means one sender can't publish into a channel it wasn't granted, and you can revoke or rotate a single integration without touching the others. Each token also reports its last-used time and 24-hour request count so you can tell which endpoints are actually receiving traffic.