Webhooks

Subscribe to workroom and integration events. Each delivery is HMAC-signed so you can verify the source.

The 30-second version

AtelyaOS sends outgoing webhooks for workroom lifecycle events and supported integration formats. Configure them under Settings → Integrations → Webhooks. Each delivery includes an HMAC signature derived from a workspace-scoped secret. A public typed-event REST subscription model (/api/v1/webhooks) ships with the public API in Q2 2026.

Why this matters

Workrooms produce events your other systems care about — a new deliverable was approved, a revision was requested, a credit threshold was crossed. Webhooks are the cheap, durable way to feed those events into your existing tools (Slack, Salesforce, Zendesk, your CRM) without polling.

How it works (today)

Configuring an outgoing webhook

1. Go to Settings → Integrations → Webhooks.
2. Click Add webhook bridge.
3. Pick a target format:
   • Slack — formatted message to a Slack incoming-webhook URL.
   • Salesforce — formatted REST POST.
   • Zendesk — ticket-shaped payload.
   • Intercom — conversation-shaped payload.
   • Generic JSON — flat JSON for your own consumer.
   • Custom — full control over headers, body, auth.
4. Enter the destination URL.
5. Pick the events to subscribe to.
6. Save.

[SCREENSHOT: webhook bridge configuration page]

Delivery and retries

Webhook deliveries are queued via Inngest. On non-2xx response, AtelyaOS retries with exponential backoff. Failed deliveries appear in the activity log with the response code and body.

Signing

Each webhook delivery includes an HMAC-SHA256 signature header, computed over the request body using a workspace-scoped webhook secret. To verify on receipt:

import crypto from "node:crypto";
 
function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

The exact header name and any prefix on the signature value are shown when you create the webhook bridge.

Inbound webhooks (received by AtelyaOS)

AtelyaOS also receives webhooks from a few external systems:

• Stripe — billing events (subscription created, invoice paid, etc.). Verified via Stripe's signing scheme.
• WhatsApp Business API — for the WhatsApp connector.
• OAuth provider callbacks — Notion / Google / Slack token exchange.
• MCP server bridges — when a connected MCP server pings AtelyaOS.

These are platform-managed; you don't configure them yourself.

Coming with the Q2 2026 public API

When the public API ships, an additional REST-based webhook subscription model becomes available:

• POST /api/v1/webhooks — register a subscription.
• Stable typed event names: workroom.completed, workroom.revision_requested, deliverable.exported, credits.low, credits.exhausted, agent.updated.
• Per-event filters (e.g. only fire for a specific workspace or workroom).
• Signed payloads with rotation support.

The current bridge model continues to work alongside this — they're complementary.

Common pitfalls

• Not verifying the HMAC. Webhook URLs leak. Always verify the signature so a forged POST can't trigger your downstream system.
• Blocking the response. Process the webhook quickly (or queue it). AtelyaOS retries on non-2xx, and a slow consumer means duplicate deliveries.
• Subscribing to everything. Pick the specific events you care about. "All events" produces noise that's hard to triage.
• Coding against internal session endpoints instead of webhooks. If you're polling our internal endpoints to detect a workroom finishing, switch to webhooks. They're cheaper and more durable.

What's next

• API overview — public API timeline.
• Authentication — API key model coming Q2 2026.
• Tool integrations — the OAuth path for inbound automation.