Webhooks: Real-Time Notifications for Architecture Changes

Last week a team told me they renamed a core system in Archyl — changed "UserService" to "AccountService" across the C4 model, updated the relationships, rewrote the ADR. Clean, thorough work. The problem? The platform team that depended on that system found out four days later, when their deployment pipeline referenced a name that no longer existed.

Nobody told them. Not because anyone was careless — there just wasn't a mechanism for it. Architecture documentation is typically a pull model. You go look at the diagram. You go read the ADR. If you don't go look, you don't know.

This is the same pattern that plagued software development before CI/CD notifications became standard. Code changes used to be something you discovered when you pulled main. Today, every merge, every failed build, every deploy fires a notification somewhere. Architecture changes deserve the same treatment.

Push Notifications for Your Architecture

Archyl now supports webhooks. When something changes in your C4 model — a system is created, a container is deleted, a relationship is updated, a release ships — Archyl sends an HTTP POST to any endpoint you configure, with a JSON payload describing exactly what happened.

The idea is straightforward: your architecture is a living system. People and tools should be able to subscribe to its changes the same way they subscribe to deploy events or pull request notifications. Instead of asking "did anything change?", the answer comes to you.

44 Event Types

We didn't want to ship a notification system that only covered half the model. Webhooks fire across everything Archyl tracks:

C4 Elements — System, container, component, and code element creation, updates, and deletions. The core of your architecture model.

Relationships — When connections between elements are created, modified, or removed. This is often the most important signal — a new dependency between two systems is the kind of change that multiple teams need to know about.

ADRs & Documentation — Architecture Decision Records and project docs being created, updated, or deleted. When someone writes a new ADR explaining why the team is migrating from REST to gRPC, the people affected should hear about it immediately, not three sprints later.

Flows — User and system flow changes. New flows, updated steps, deleted flows.

Overlays — Visual grouping changes on your diagrams.

Releases — Deployment events across environments. Combined with release management, this gives you a full push-based deployment notification pipeline.

Requests — Architecture change requests being opened, reviewed, or merged.

API Contracts & Event Channels — Spec changes and async messaging updates linked to your architecture.

Discovery & Insights — AI-powered discovery completions and new architecture insights.

Forty-four event types in total. You pick the ones you care about — subscribe to everything, or just the five events that matter to your workflow.

How It Works

Setting up a webhook takes about thirty seconds.

You give it a name (something descriptive — "Slack notifications", "Audit log sync", "CI trigger"). You provide a URL — any HTTP endpoint that can receive a POST request. You optionally set a secret for signature verification. Then you pick which events should trigger it.

You can also scope a webhook to specific projects. An organization-wide webhook that fires on every change across every project is useful for audit logging. A project-scoped webhook that only fires on release events for your payment system is useful for the team that owns it.

When a matching event occurs, Archyl sends an HTTP POST to your URL with a JSON payload containing:

  • Event type — Which of the 44 events triggered this delivery
  • Entity — The full details of the element that changed
  • Actor — Who made the change (user ID, name, email)
  • Project — Which project this happened in
  • Timestamp — When the change occurred
  • Organization — Which organization this belongs to

The payload gives you everything you need to react to the change — display it, log it, trigger a pipeline, or sync it to another system.

Security: HMAC-SHA256 Signatures

Every webhook request includes an X-Archyl-Signature header with the format sha256=<hex digest> — an HMAC-SHA256 hash of the raw request body, computed using your secret. You'll also get X-Archyl-Event (the event type) and User-Agent: Archyl-Webhook/1.0 so you can identify the source.

On the receiving end, you strip the sha256= prefix, recompute the HMAC-SHA256 hash with your copy of the secret against the raw body bytes, and compare using constant-time comparison. If they match, the request is authentic. If they don't, someone is sending you forged events.

This is the same signing scheme used by GitHub, Stripe, and most webhook providers. It's simple, well-understood, and easy to implement in any language. No OAuth flows, no token rotation, no certificate management. Just a shared secret and a hash. See the webhook docs for complete verification examples in Go, Node.js, and Python.

If you don't set a secret, the signature header is omitted. Fine for internal endpoints behind a VPN. Not recommended for anything exposed to the internet.

What You Can Build With This

The most obvious use case is chat notifications. Slack, Microsoft Teams, and Discord all support incoming webhooks — paste their URL into Archyl, select the events you care about, and architecture changes start appearing in your channel. A new system was added. An ADR was approved. A release shipped to production. Your team sees it without opening Archyl.

But notifications are just the beginning.

Sync to external systems — Push architecture changes to a CMDB, an internal wiki, or a service catalog. When a container is renamed in Archyl, your service catalog updates automatically.

Trigger CI/CD pipelines — When an architecture change request is merged, kick off a pipeline that regenerates infrastructure config, updates Terraform modules, or validates that the actual deployment matches the documented architecture.

Audit trail — Forward every event to an external logging system — Elasticsearch, Splunk, a simple append-only database. Seven days of delivery history in Archyl is useful for debugging; a permanent external log is useful for compliance.

Custom dashboards — Build an internal dashboard that reacts to architecture events in real time. Track how often the architecture changes, which teams are most active, which systems are most volatile.

The point is that webhooks turn Archyl into an event source. Your architecture model becomes something other systems can subscribe to, react to, and build on top of.

Delivery Tracking

Every webhook delivery is logged. You can see the full history for any webhook: which event triggered it, the request payload that was sent, the response status code, the response body, and the timestamps for when it was sent and when the response arrived.

Deliveries are retained for seven days. Long enough to debug integration issues, short enough that we're not storing your endpoint's response bodies indefinitely.

When a delivery fails — a 500 from your server, a timeout, a DNS resolution error — it shows up with a red status. You can inspect the error, fix your endpoint, and retry with one click. The retry sends the exact same payload, so your endpoint processes the original event as if it had succeeded the first time.

No automatic retries. We considered exponential backoff, but in practice, most webhook failures are either transient (your server was restarting) or structural (the URL is wrong). For transient failures, the manual retry button is faster than waiting for backoff. For structural failures, automatic retries just generate noise.

Getting Started

  1. Go to Organization Settings > Webhooks
  2. Click Create Webhook
  3. Enter a name, paste your endpoint URL, set a secret
  4. Select the events you want to subscribe to
  5. Optionally filter to specific projects
  6. Click Send Test to verify your endpoint receives the payload
  7. Save, and you're live

The test delivery sends a ping event with a sample payload so you can confirm your endpoint is reachable, your secret is configured correctly, and your handler processes the JSON as expected. Do this before subscribing to real events.

Architecture as an Event Stream

We've been building toward a version of architecture documentation that isn't a static artifact — it's a living, connected part of your development workflow. Marketplace Integrations bring external data into your architecture. Webhooks push architecture data out to your tools.

The combination is powerful. Your architecture workspace isn't just a place you go to look at diagrams. It's a hub that receives operational data from your monitoring tools and emits change events to your communication and automation tools. Data flows in both directions.

Architecture documentation that nobody looks at is useless. Architecture documentation that notifies you when it matters — that's infrastructure.

Want to see how other features connect your architecture to your workflow? Check out Marketplace Integrations for bringing live data onto your diagrams, or Release Management for tracking deployments across your C4 model.