webhook-transforms

Webhook Transforms

Contract

This skill guarantees:

• External events are transformed into brain pages with proper citations
• Raw payloads are preserved (dead-letter queue if transform fails)
• Entity extraction runs on every transformed event
• Input sanitization: no raw HTML/script passes to brain pages
• Error handling: transform failure logs raw payload, retries once

Phases

1. Define transform. Map event schema to brain page format:

   • Input: raw webhook payload (JSON)
   • Output: brain page content (markdown) + metadata (slug, type, citations)
   • Must sanitize: strip HTML tags, escape script content

2. Wire up delivery. Point the external service at whatever endpoint the operator exposes (host-side reverse proxy, or the agent harness's own inbound channel). The brain itself is not the webhook listener — events land with the agent, which runs the transform and writes over MCP.

3. On event received:

   • Parse payload
   • Run transform function
   • Write brain page via page_put (indexing happens on write — the brain is DB-canonical, no separate sync step)
   • Extract entities, run enrichment
   • Add timeline entries to mentioned entities via add_timeline_event

4. Error handling:

   • If transform throws: preserve the raw payload via put_raw_data and write a dead-letter page at _dead-letter/{timestamp} referencing it
   • Surface error type to agent
   • Retry once
   • Don't lose events

Example Transforms

SMS Received

Input: {from: "+1555...", body: "Meeting moved to 3pm", timestamp: "..."}
Output: Timeline entry on sender's brain page + task update if action item detected

Meeting Completed

Input: {title: "Weekly sync", attendees: [...], transcript: "...", summary: "..."}
Output: Delegate to meeting-ingestion skill

Social Mention

Input: {platform: "twitter", author: "@handle", text: "...", url: "..."}
Output: Brain page in media/ + entity extraction + backlinks