Hopsule API: Webhooks

Introduction to Hopsule Webhooks

Hopsule Webhooks provide a powerful mechanism for engineering organizations to maintain real-time synchronization between their decision-making processes and their external tooling. In a decision-first environment, the speed at which an accepted constraint is communicated to the rest of the organization determines the effectiveness of its enforcement. Webhooks act as the nervous system of your organizational memory, pushing critical updates about Decisions, Memories, and Context Packs to your custom applications, CI/CD pipelines, and communication platforms the moment they occur.

By leveraging webhooks, teams can move beyond manual checks and periodic polling. Instead of forcing developers to constantly query the Hopsule API for updates, Hopsule proactively notifies your infrastructure when the state of your governance changes. This ensures that the principle of "enforcement is remembrance" is applied instantly across your entire ecosystem, whether that involves updating a documentation site, triggering a security audit, or notifying a lead engineer about a detected conflict in the Knowledge Graph.

Webhooks are designed for high reliability and security, ensuring that your Context Packs remain portable and your Memories remain immutable even as they are shared across disparate systems. Whether you are building a custom dashboard to visualize organizational judgment or integrating with an enterprise resource planner, webhooks provide the necessary hook into the lifecycle of every decision your team makes.

Available Webhook Events

Hopsule emits a variety of events that cover the entire lifecycle of your organizational context. Each event is designed to provide maximum context while maintaining the integrity of the Memories and Decisions being referenced. Understanding these events is crucial for building robust integrations that respond correctly to the evolving state of your engineering governance.

Decision Lifecycle Events

• decision.created: Triggered whenever a new decision is drafted. This is particularly useful for notifying stakeholders that a new proposal is awaiting review.

• decision.pending: Triggered when a draft decision is moved to the pending state, signaling that it is ready for formal evaluation or voting.

• decision.accepted: Emitted when a decision is officially accepted. This is a critical event for enforcement, as it signals that the decision is now a binding constraint for the team.

• decision.deprecated: Triggered when a decision is no longer valid. This allows external systems to remove enforcement rules or archive related documentation.

Memory and Context Events

• memory.created: Emitted whenever a new, append-only memory entry is added to the system. Since memories provide the "why" behind decisions, this event is vital for maintaining a historical audit trail in external logging systems.

• capsule.activated: Triggered when a Context Pack (Capsule) is marked as active. This informs integrated tools that a specific bundle of decisions and memories should now be considered the primary source of truth for a project.

• capsule.frozen: Emitted when a capsule is locked to prevent further changes, ensuring the preservation of context for a specific point in time, such as a product release or a major architectural milestone.

System and Intelligence Events

• conflict.detected: Triggered when Hopper identifies a contradiction between a new proposal and an existing, accepted decision. This event allows teams to automate the escalation of governance conflicts to senior leadership.

• graph.updated: Emitted when significant changes occur within the Knowledge Graph, allowing external visualization tools to refresh their representation of the organization's decision relationships.

Configuring Webhook Endpoints

To begin receiving events, you must register a destination URL where Hopsule will send the POST requests. This can be managed through the Hopsule Dashboard or programmatically via the Hopsule API. Each endpoint can be configured to listen for all events or a specific subset, allowing you to tailor the data flow to the specific needs of each integration.

When creating an endpoint via the Hopsule API, you will use the POST /v1/webhooks endpoint. You must provide a url that is accessible over the public internet and uses HTTPS to ensure the preservation of your organization's data during transit. Optionally, you can provide a description to help your team identify the purpose of the integration within the Hopsule Dashboard.

Important: Your server must respond with a 2xx status code within five seconds of receiving a webhook. If Hopsule does not receive a successful response, it will consider the delivery a failure and initiate the retry policy. Ensure that your endpoint performs minimal processing synchronously—ideally, it should acknowledge receipt and queue the event for background processing.

Webhook Payload Format

Every webhook sent by Hopsule follows a consistent JSON structure. This predictability allows you to build generic handlers that can route events based on their type before deep-diving into the specific data payload. The payload includes metadata about the event itself, as well as the relevant entity (Decision, Memory, or Capsule) that triggered the notification.

The top-level object contains the following fields:

• id: A unique identifier for the specific webhook delivery.

• created_at: An ISO 8601 timestamp indicating when the event was generated.

• type: The event string (e.g., decision.accepted).

• data: An object containing the full representation of the affected entity.

For example, a decision.accepted event will include the full decision object in the data field, including its version history, associated tags, and links to the Memories that explain the reasoning behind the acceptance. This ensures that the receiving system has all the context necessary to enforce the decision without needing to make additional calls back to the Hopsule API.

Webhook Security and Verification

Security is a baseline guarantee at Hopsule, and webhooks are no exception. Because webhook endpoints are public URLs, it is essential to verify that incoming requests actually originated from Hopsule and have not been tampered with during transit. Hopsule uses HMAC-SHA256 signatures to provide this assurance.

When you create a webhook endpoint, Hopsule generates a unique Signing Secret. For every delivery, Hopsule computes a signature by hashing the raw request body with this secret. This signature is then included in the X-Hopsule-Signature header of the request. To verify the request, your server should compute its own HMAC-SHA256 hash using the secret and the received body, then compare it to the header value.

Tip: Always use a constant-time string comparison function when verifying signatures to prevent timing attacks. Additionally, Hopsule includes a timestamp in the signature header to prevent replay attacks. You should verify that the timestamp is within a reasonable window (e.g., 5 minutes) of your server's current time.

Retry Policy and Reliability

Hopsule is built to ensure that organizational memory is never lost, and this philosophy extends to our delivery infrastructure. If your webhook endpoint is temporarily unavailable or returns an error (any non-2xx status code), Hopsule will automatically attempt to redeliver the event using an exponential backoff strategy.

The retry logic follows these parameters:

1. Immediate Retry: The first retry happens within seconds of the initial failure.

2. Exponential Backoff: Subsequent retries occur at increasing intervals (e.g., 1 minute, 5 minutes, 30 minutes, 2 hours).

3. Maximum Retries: Hopsule will attempt to deliver the event up to 12 times over a 24-hour period.

4. Disabling Endpoints: If an endpoint consistently fails for more than 48 hours, Hopsule will automatically disable it and notify the organization administrators via the Hopsule Dashboard.

This rigorous approach ensures that even during periods of infrastructure instability, your decision-making history and governance updates eventually reach their destination. You can view the status of all deliveries, including failed attempts and response codes, in the Activity Feed of the dashboard.

Managing and Testing Webhooks

The Hopsule Dashboard provides a comprehensive interface for managing your webhook integrations. From the settings menu, you can view a list of all configured endpoints, their current status (Active, Failing, or Disabled), and the specific events they are subscribed to. This centralized view is essential for maintaining governance over your integrations.

To facilitate development, Hopsule includes a Test Webhook feature. This allows you to send a mock event payload to your endpoint with a single click. You can select the event type and see the exact response your server returned, including headers and body. This is invaluable for debugging signature verification logic or payload parsing without having to manually trigger real events within your production Context Packs.

Tip: Use the Hopsule CLI to list and test webhooks directly from your terminal. The CLI provides a streamlined way to rotate signing secrets and update endpoint URLs during local development cycles.

Example Integration: Slack Notifications

One of the most common use cases for webhooks is keeping the team informed about changes in organizational judgment. By connecting Hopsule to a Slack incoming webhook or a custom Slack app, you can ensure that every time a decision is accepted, a notification is posted to the relevant engineering channel.

When your endpoint receives a decision.accepted event, your handler can extract the decision title, the author, and the link to the Knowledge Graph. By posting this information to Slack, you turn a silent governance change into a moment of collective remembrance. This visibility encourages team members to review the reasoning behind the decision and ensures that the new constraint is fresh in everyone's mind as they return to their IDEs.

Example Integration: Jira Governance

For larger organizations, webhooks can be used to bridge the gap between Hopsule's decision-first model and traditional project management tools like Jira. When Hopper detects a conflict (conflict.detected), a webhook can automatically trigger the creation of a Jira ticket assigned to the project lead.

The Jira ticket can include a link to the Hopsule Dashboard where the conflicting decisions are visualized in the Brain. This ensures that governance issues are not buried in an AI assistant's suggestions but are instead integrated into the team's existing workflow for resolution. Once the conflict is resolved and one of the decisions is deprecated, another webhook (decision.deprecated) can be used to automatically close the Jira ticket, maintaining a perfect sync between your organizational memory and your task tracking.

Rate Limits and Best Practices

To maintain system stability for all users, the Hopsule API enforces rate limits on webhook deliveries. These limits are based on your organization's plan tier (Free, Pro, or Enterprise). If your system generates an unusually high volume of events in a short period, Hopsule may queue deliveries to stay within these limits.

To ensure the best performance for your integrations, follow these best practices:

• Idempotency: Always check the id of the incoming webhook. If you have already processed that ID, ignore the request. This prevents duplicate processing in the event of a retry.

• Asynchronous Processing: Do not perform heavy database operations or external API calls directly within the webhook handler. Use a message queue to process the event data.

• Version Pinning: When consuming the data object, be aware that Hopsule may add new fields over time. Ensure your parser is resilient to additional properties.

• Security: Never share your Signing Secret and rotate it immediately if you suspect it has been compromised.

For more information on rate limits and plan-specific features, please refer to the Hopsule API Reference and the Hopsule Enterprise documentation. By following these guidelines, you can build a robust, context-aware integration layer that ensures your team's most important decisions are always remembered and enforced.