Webhooks & External Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/notifications/webhook.ts
• src/lib/actions/webhook.ts
• src/app/(app)/settings/webhooks/page.tsx/settings/webhooks/page.tsx)
• src/lib/notifications/reminderContent.ts
• src/lib/mcp/server.ts
• PRODUCT.md
• CLAUDE.md

Webhooks and external integrations in Hearth notify other platforms when contracts, warranties, or vehicles cross reminder thresholds. This system allows the household to integrate Hearth data with external automation platforms like Home Assistant or MCP-compatible LLM agents.

Sources: src/app/(app)/settings/webhooks/page.tsx:23-27, PRODUCT.md:32-33

Webhook Architecture

Hearth uses outbound webhooks to push event data to user-defined HTTP endpoints. Only users with the ADMIN role manage webhook configurations, including adding, toggling, and deleting endpoints.

Delivery Logic

The system follows a specific sequence for delivering notifications:

1. The scheduler identifies a record crossing a reminder threshold.
2. The system retrieves all enabled webhook endpoints.
3. The delivery engine signs the payload using HMAC-SHA256 if a secret is configured.
4. The engine performs a POST request to the destination URL with a 10-second timeout.
5. The system logs every delivery attempt (success or failure) in the database.

The diagram shows the logic flow from a reminder event to the final database logging of the delivery attempt.
Sources: src/lib/notifications/webhook.ts:24-65, src/lib/actions/webhook.ts:18-21

Security and Validation

Hearth implements several security measures for outbound webhooks:

• Outbound Safety: URLs are validated against assertSafeOutboundUrl to prevent access to internal cloud metadata addresses or non-HTTP(S) schemes.
• Payload Signing: If an endpoint has a secret, Hearth adds an X-Webhook-Signature header containing an HMAC-SHA256 hash of the request body.
• Timeout: Requests are aborted if they exceed 10,000 milliseconds.

Sources: src/lib/notifications/webhook.ts:7-13, src/lib/actions/webhook.ts:40-51

Event Payloads

Hearth sends structured JSON payloads. Vehicles receive their own specific event type and URL format distinct from contracts and warranties.

Payload Data Model

Field	Type	Description
event	String	The type of event (e.g., contract.expiring, vehicle.expiring, webhook.test).
kind	String	The record type: contract, warranty, or vehicle.
id	String	The unique identifier of the record.
title	String	The title or description of the record.
daysRemaining	Number	Integer count of days until the due date.
endDate	String	ISO formatted date (YYYY-MM-DD) of expiry.
url	String	Direct link to the record in the Hearth UI (requires APP_URL env var).

Sources: src/lib/notifications/webhook.ts:79-88, tests/unit/reminderContent.test.ts:133-157

Model Context Protocol (MCP) Server

Hearth includes a read-only MCP server that allows Large Language Model (LLM) agents to query household data.

Configuration

• Access: The endpoint is mounted at /api/mcp.
• Authentication: Gated by an Authorization: Bearer header using the MCP_TOKEN environment variable.
• Constraints: The server only provides read tools. It never includes write tools, credentials, or raw document bytes.

Available Tools

• list_contracts: Retrieves all household contracts.
• get_contract: Retrieves details for a specific contract.
• search_contracts: Searches contracts by title or provider.
• upcoming_renewals: Lists active contracts ending within a specified timeframe.
• spend_summary: Provides monthly spend estimates.

Sources: CLAUDE.md:104-109, PRODUCT.md:32-33

Managing Endpoints

Administrators manage webhooks via the Settings interface.

The sequence shows the process of adding a new webhook endpoint through the admin interface.
Sources: src/lib/actions/webhook.ts:23-64, src/app/(app)/settings/webhooks/page.tsx:32-60

Admin Actions

Action	Function	Description
Add	createWebhookEndpoint	Creates a new named endpoint with an optional signing secret.
Toggle	toggleWebhookEndpoint	Enables or disables an existing endpoint without deleting it.
Test	sendTestWebhookAction	Sends a webhook.test event to verify connectivity and signing.
Delete	deleteWebhookEndpoint	Permanently removes the endpoint and stops deliveries.

Sources: src/lib/actions/webhook.ts:23-100

Summary

The Webhooks and External Integrations module provides a robust mechanism for Hearth to interact with external services. By combining secure outbound webhooks for real-time notifications with an MCP server for LLM-based queries, Hearth ensures household data is accessible for automation while maintaining privacy and administrative control.