Setting Up Webhooks and Real-Time Notifications

Real-time synchronization is the cornerstone of a decision-first engineering culture. While the Hopsule Dashboard serves as the central authority for your organization's judgment, your existing workflows—from continuous integration pipelines to communication platforms—require immediate awareness when the context shifts. By configuring webhooks through the Hopsule API, you ensure that every accepted decision and every preserved memory is instantly propagated across your entire technical ecosystem, transforming passive remembrance into active enforcement.

This article provides an exhaustive guide to implementing webhooks, enabling your team to build custom integrations that react to the lifecycle of decisions, the addition of memories, and the freezing of Context Packs. Whether you are automating compliance checks or updating external dashboards, the Hopsule API provides the reliable, secure, and real-time connectivity required for modern, AI-forward engineering organizations.

Prerequisites

Before you begin configuring webhooks, ensure you have met the following requirements within your organization:

• Administrative Access: You must have administrative or owner-level permissions for your organization in the Hopsule Dashboard to manage API settings and webhook configurations.

• Active Hopsule API Key: A valid API key is required to authenticate requests. You can generate this in the Settings section of the Hopsule Dashboard.

• Destination Endpoint: A publicly accessible URL capable of receiving and processing HTTP POST requests. This endpoint must be secured via TLS 1.3 to align with Hopsule’s security standards.

• Defined Use Case: Identify which events (decisions, memories, or capsules) are critical to your external workflows to avoid unnecessary data processing.

Step 1: Navigating to Webhook Management

To begin the configuration, log in to the Hopsule Dashboard. From the primary navigation sidebar, select the Settings icon located at the bottom-left of the interface. Within the settings view, locate the API & Integrations tab. Here, you will find the Webhooks sub-section, which displays an overview of your existing active and inactive hooks.

Click the Add Webhook button in the top-right corner of the Webhooks panel. This will open the configuration interface where you will define the parameters for your real-time notification stream.

Step 2: Defining the Endpoint and Description

In the Payload URL field, enter the destination address where Hopsule should send event data. This URL must start with https://. Hopsule enforces encrypted transit for all webhook deliveries to ensure the preservation of your organizational context.

In the Description field, provide a clear, professional label for the webhook. For example, "Production CI/CD Enforcement Hook" or "Engineering Leadership Notification Stream." This helps other team members understand the purpose of the integration without needing to inspect the destination code.

Step 3: Selecting Event Triggers

Hopsule allows you to subscribe to specific events to ensure your systems only react to relevant changes. You can choose to "Send everything" or "Select individual events." For most high-governance environments, selecting individual events is recommended to maintain a clean audit trail.

Decision Events

Decisions are the primary unit of authority in Hopsule. Subscribing to these events allows you to enforce governance in real-time.

• decision.created: Triggered when a new draft is initiated, often via Hopper or the Hopsule CLI. This is useful for alerting reviewers that a new proposal requires their judgment.

• decision.accepted: The most critical event. This signals that a decision has moved from a proposal to an enforceable constraint. Use this to trigger CI/CD gate updates or to refresh the Hopsule for VS Code extension context for your developers.

• decision.deprecated: Triggered when an existing commitment is no longer valid. This event is vital for removing outdated enforcement rules from your automated systems.

• decision.updated: Triggered when the metadata or description of a decision is modified.

Memory Events

Memories provide the "why" behind your decisions. They are append-only and represent the persistent history of your team's reasoning.

• memory.added: Triggered whenever a new memory entry is linked to a decision or a project. This ensures your external context mirrors the latest lessons learned by the team.

Context Pack (Capsule) Events

Capsules are portable bundles of decisions and memories designed to survive time and organizational shifts.

• capsule.frozen: Triggered when a Context Pack is moved to a "Frozen" state, meaning it is ready for distribution or long-term preservation. This is an ideal trigger for archiving context in external compliance systems.

• capsule.active: Triggered when a capsule is deployed to a project, signaling that its contained decisions are now in effect for that specific context.

Step 4: Configuring Security and Signatures

Security is a baseline guarantee in Hopsule. When you create a webhook, the Hopsule Dashboard generates a unique Signing Secret. This secret is used to create a cryptographic signature for every payload sent to your endpoint.

Your server should use this secret to verify the signature header included in each request. This ensures that the data truly originated from Hopsule and has not been tampered with in transit. Never share this secret or commit it to public version control. If a secret is compromised, use the Rotate Secret button in the Hopsule Dashboard immediately.

Step 5: Testing and Activation

Before moving to a production state, use the Send Test Event feature. This sends a dummy payload to your endpoint, allowing you to verify that your server correctly receives, validates, and acknowledges the request. Hopsule expects a 2xx success code in response. If your server returns anything else, Hopsule will log a delivery failure.

Once testing is successful, toggle the Status to Active. Your webhook is now live and will begin streaming real-time updates as your team makes decisions and records memories.

Tips and Best Practices

• Implement Idempotency: Your endpoint should be designed to handle the same event multiple times gracefully. In rare network scenarios, Hopsule may retry a delivery to ensure the preservation of the message.

• Asynchronous Processing: To maintain high performance, your webhook receiver should acknowledge the request immediately with a 202 Accepted and process the data in a background task.

• Use the Hopsule API for Enrichment: Webhook payloads contain essential information, but you can use the Hopsule API to fetch the full Knowledge Graph or related Memories if your integration requires deeper context.

• Monitor Delivery Logs: Regularly check the Activity Feed in the Hopsule Dashboard to monitor for webhook delivery failures or timeouts.

• Leverage Hopper: Ask Hopper to suggest which events are most relevant for your specific project type. Hopper can analyze your team's decision frequency to recommend optimal notification settings.

• Secure Your Endpoint: Beyond signature verification, consider IP whitelisting if your infrastructure requires an additional layer of perimeter security.

Troubleshooting

If your integrations are not receiving updates as expected, consult the following table to identify and resolve common configuration issues.

Related Articles

• Managing API Keys and Organization Security: Learn how to secure your Hopsule environment and manage access for external tools.

• Understanding the Decision Lifecycle: A deep dive into the transitions from Draft to Accepted and how they impact your organization's governance.

• Integrating Hopsule with CI/CD: How to use webhooks and the Hopsule CLI to enforce decisions during the automated build process.