Webhook Transforms

---
name: webhook-transforms
version: 1.0.0
description: |
  Generic framework for converting external events (SMS, meetings, social mentions)
  into brain-ingestible signals. Define a transform function, point the event source
  at the receiving endpoint, and incoming events get processed through the brain
  pipeline.
triggers:
  - "set up webhook"
  - "process webhook event"
  - "transform this event"
tools:
  - page_put
  - add_timeline_event
  - search
  - put_raw_data
mutating: true
---

# 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
```

## Output Format

Event transformed and written to brain. Report: "Webhook: {event_type} from {source}
→ {brain_page_slug}"

## Anti-Patterns

- Passing raw HTML/script to brain pages (XSS risk)
- Silently dropping events when transform fails (use dead-letter queue)
- Processing webhooks without entity extraction
- Not sanitizing external input before brain writes