Webhooks & alerts

Stoa can push real-time notifications to your existing chat tools and monitoring systems as events happen on the platform: a knowledge base updated, a user created, a workflow parked waiting on an approver, and more.

TIP

Today, webhook delivery is set up by your technical team or your delivery engineer directly, rather than from a screen in the admin UI. This page explains what's possible so you know what to ask for.

What you can subscribe to

A webhook subscribes to one or more of the same fine-grained actions the platform already records in your audit log: things like a knowledge base being created or updated, a user being added, a role changing, or a workflow parking on a human approver. There isn't a separate, curated list of "webhook events" distinct from that: if it's something the platform would log, it's something a webhook can fire on.

You can point one webhook at several actions, or set up separate webhooks for separate destinations (change-management events to one channel, approval requests to another).

Supported destinations

Stoa formats outgoing webhook payloads to fit each destination:

Slack

Point Stoa at an Incoming Webhook URL from your Slack workspace. Stoa formats the message as a Slack card with the event title, key fields, and a link back to the relevant Stoa page.

Microsoft Teams

Point Stoa at a Teams Incoming Webhook URL. Stoa formats the payload as an Adaptive Card so it renders cleanly in the Teams channel.

Email

Point Stoa at an HTTPS endpoint provided by a notification or email-relay service you already use, one that turns an incoming webhook into an outgoing email. Stoa doesn't send the email itself here: an "Email" destination posts the same JSON payload a generic HTTP destination does, just labeled differently so you can tell at a glance what it's for.

If what you actually want is Stoa emailing someone directly through your own mail server, that happens for two specific things today (welcome emails for new accounts and a notice when a workflow is waiting on an approver), configured under Email (SMTP), not through a webhook.

Generic HTTP

For SIEMs, custom dashboards, ticketing systems, or anything else, point Stoa at any HTTPS endpoint you control. The payload is a JSON object with the event, a timestamp, the actor, the resource, and a small data block specific to the event. Your endpoint can do whatever it wants with it.

Setting one up

Because there's no self-service screen for this yet, ask your delivery engineer or your own integration team to register a webhook on your behalf. Have ready:

• A name, so you remember what it's for.
• The destination type (Slack, Teams, email, or generic HTTP) and the destination address or URL.
• The actions you want it to fire on.
• An optional signing secret (see below), if the destination is a generic HTTP endpoint you control.

Verifying requests with a signature

For generic HTTP destinations, a signing secret can be attached when the webhook is registered. Stoa then signs every outgoing request with that secret (HMAC-SHA256) and attaches the signature as a header.

On your side, recompute the signature using the same secret and compare it to the header. If they match, the request really came from your Stoa deployment. If they don't, drop the request. This protects your endpoint from anyone who happens to learn its URL.

TIP

Slack and Teams webhook URLs are themselves the secret: they're long, random, and only known to your workspace. Signing is most useful for generic HTTP endpoints that you've exposed to the internet.

Delivery is best-effort

Each matching event is delivered once, immediately. If the destination is unreachable or returns an error, that delivery is not automatically retried, and the failure isn't recorded in the audit log either. Webhooks are a convenience signal for staying informed in near real time, not a guaranteed or auditable delivery channel.

For anything you absolutely cannot afford to miss (compliance-critical actions, for example), pair webhooks with a periodic review of the audit log, which is the durable record.

Testing before you rely on it

Whoever registers a webhook for you can also trigger a one-off test delivery through the same channel used to set it up, so you can confirm the destination renders correctly and that nothing in between (a firewall, a proxy) is silently dropping the request before treating it as live.

Next

• Email (SMTP) for slower, persistent notifications alongside real-time webhooks.
• Audit logging for the durable record every webhook is drawn from.
• System status to confirm the platform is healthy if deliveries start failing.