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.

Webhooks are managed from Integrations → Webhooks. Anyone whose role grants webhook management can register, edit, test, pause, and remove them without involving your delivery engineer.

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

Go to Integrations → Webhooks and choose New Webhook. You'll be asked for:

• A name, so you remember what it's for.
• The destination type (Slack, Teams, email relay, or generic HTTP) and the destination URL.
• The events to fire on, chosen from a list of everything the platform records. Each one shows both a plain name and the exact action it matches. A webhook with no events selected receives nothing.
• An optional signing secret (see below), which is worth setting for any endpoint of your own.

Before saving, use Send test to fire a sample delivery at the URL as you've typed it. The test goes out whether or not the webhook has been saved yet, so you can prove a destination works before committing to it, and the screen tells you what the receiver said.

Once saved, a webhook can be paused and resumed from the list without losing its settings, which is the thing to reach for when a receiver is being worked on. Registering, changing, testing, and removing webhooks are themselves recorded in the audit log.

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.