Webhooks

Webhooks are how external systems subscribe to events that happen inside Stoa. Instead of polling, your system registers an endpoint, and Stoa pushes a JSON payload to it whenever a matching event happens. This page covers what you can subscribe to, how delivery works, and how to wire it into your downstream systems.

What you can subscribe to

A webhook subscribes to the same actions Stoa already records in its audit trail, not a short curated list of "business events." In practice that covers most of what happens in a deployment, including:

• Agents and skills. Created, updated, or removed.
• Knowledge bases and files. A knowledge base created, updated, or reindexed; a file uploaded, downloaded, or removed.
• Users and roles. A user or role added, changed, or removed.
• Workflows and schedules. A workflow launched or cancelled; a scheduled job firing.
• Research jobs. A research job submitted or cancelled.
• Sign-in activity. Sign-ins, sign-outs, and password changes.
• Configuration changes. Settings, branding, and integration changes.

You can subscribe one webhook to several of these, or register multiple webhooks, each tuned to a different destination.

Supported destinations

Stoa ships with support for four destination types.

• Slack. Provide an incoming webhook URL from your Slack workspace. Payloads arrive as a formatted message with the event name and key details.
• Microsoft Teams. Provide an incoming webhook URL from a Teams channel. Payloads arrive as a simple card that renders in the channel.
• Email. Provide the HTTPS URL of a notification or email-relay service that turns a webhook into an email. This is a label, not a separate transport: Stoa posts the same JSON body a generic destination gets, it's just tagged "Email" so the list of registered webhooks stays readable. Stoa does not send this one through its own mail server.
• Generic HTTP endpoint. Provide any HTTPS URL. Payloads are sent as POST with a JSON body. Use this for SIEM systems, log pipelines, ticketing tools, or anything else that can accept a JSON POST.

For Slack and Teams, the formatting is basic and handled for you. For email and generic endpoints, you receive the structured event and can transform it however you need on your side.

Payload format

Every webhook delivery carries the event type, the resource it happened to (and that resource's name or ID), who triggered it, when it happened, and a short human-readable detail describing what happened. A generic HTTP payload wraps this in a JSON envelope; Slack and Teams payloads fold the same information into their respective message formats.

Verifying the signature

If you set a signing secret when you register a webhook, every outbound request to that webhook is signed with HMAC-SHA256 over the raw request body, using your secret, and the signature is sent in a request header (X-Webhook-Signature). Your endpoint should verify the signature on every request before trusting the payload.

To verify:

1. Read the signature header from the incoming request.
2. Compute HMAC-SHA256 over the raw request body using your shared secret.
3. Compare the computed signature against the header value using a constant-time comparison.
4. Reject the request if they don't match.

This protects you against spoofed events and against unauthorized callers hitting your endpoint. Slack and Teams webhook URLs are themselves effectively a secret (long, random, and only known to your workspace), so signing matters most for generic HTTP endpoints you've exposed to the internet.

Delivery is best-effort, not retried

If your endpoint returns a non-2xx status, fails to respond, or times out, Stoa does not retry. This is deliberate: a receiver that's temporarily down shouldn't get the same event hammered at it repeatedly once it recovers. The failed delivery is logged on the server and the event itself is not queued for later, so treat webhooks as a best-effort, real-time signal rather than a guaranteed delivery channel.

There is currently no delivery history to review in the product. For anything you can't afford to fully miss, pair webhooks with the audit log, which records the same underlying actions durably and can be reconciled against after the fact. Make your receiver as reliable as you reasonably can (fast, always up, acknowledges quickly), since there's no automatic second attempt to fall back on.

Registering a webhook

Webhooks are managed through Stoa's API today rather than a screen in the app. If your organization has API access and the right permission, your integration team can register a webhook directly: give it a name, a destination type (Slack, Teams, or a generic HTTPS endpoint), the destination URL, the events to subscribe to, and an optional signing secret. If you don't have API access in-house, your delivery engineer can set one up for you.

Testing a webhook

Stoa can fire a synthetic test event to a registered webhook on demand, the same shape and signature as a real one, so you can confirm delivery before relying on it. Ask your delivery engineer or your integrating team to trigger a test event after any change to the receiver, after rotating the secret, or whenever the destination URL moves.

Common patterns

• Slack alerts when a knowledge base finishes reindexing. The team channel gets a heads-up that search results are current again.
• Ops notifications on workflow and schedule activity. Ping a channel when a scheduled job fires or a workflow launches, so you know automation ran without opening Stoa to check.
• User and role change tracking. Mirror every user and role change to a compliance channel for a lightweight, real-time log.
• SIEM mirroring. A generic webhook subscribed to a broad set of events posts to a log collector, so Stoa activity sits next to the rest of your audit trail.

Next

• Webhooks (admin) for the admin-side configuration.
• Custom tools for the inverse direction: Stoa calling out to your systems.
• Audit logging for the durable record that pairs well with webhooks.