> ## Documentation Index
> Fetch the complete documentation index at: https://cofounder.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time Triggers

> Turn external events (RevenueCat, App Store, or any signed webhook) into real-time cofounder signals instead of waiting for the daily sweep.

# Real-time Triggers

The cofounder reacts to [signals](/concepts/signals). Most signals are written
by the daily anomaly detector — so a churn spike surfaces the *next* morning.
Real-time triggers close that gap: an external event becomes a signal the
instant it happens, and (for high-severity events) fires a focused run
immediately instead of waiting up to 15 minutes for the event orchestrator's
next poll.

```
webhook → verify → recordSignal() → event orchestrator (≤15m)
                                  ↘ immediate dispatch (high/critical)
```

Immediate dispatch reuses the same gating as the orchestrator — your
`proactive_mode`, `min_signal_severity`, billing, and a 30-minute per-app
cooldown — so it never storms runs or bypasses your preferences.

## RevenueCat webhooks

Subscription lifecycle events (cancellation, expiration, billing issue, refund)
become `churn_spike` signals in real time.

**Setup** — in **Settings → Data sources → RevenueCat** (after connecting your
key), copy the **Webhook URL** and **Authorization value**, then paste them into
RevenueCat → Integrations → Webhooks.

```
GET  /v1/cofounder/... → surfaced in Settings
     URL:  https://api.appeeky.com/v1/cofounder/webhooks/revenuecat
     Authorization: <your per-owner token>
POST /v1/connect/revenuecat/webhook/rotate   # rotate the token
```

Only production events are processed; `EXPIRATION` / `BILLING_ISSUE` are
high-severity (run now), while `CANCELLATION` / `SUBSCRIPTION_PAUSED` / `REFUND`
wait for the next poll. Bursts collapse to one signal per type per day.

## App Store Server Notifications

If you've configured Apple's App Store Server Notifications V2 (the same
`POST /v1/webhooks/apple` endpoint that powers the mobile inbox), subscriber
**churn** (`EXPIRED`, auto-renew off) and **refunds** now also emit a
`churn_spike` signal automatically — no extra setup. Hard billing churn
(`BILLING_RETRY`) is high-severity.

## Custom signed webhook

The reusable primitive: any external system (GitHub, Zapier, internal tooling)
can POST a signed event that becomes a signal.

**Setup** — get your URL + signing secret:

```
GET  /v1/cofounder/webhooks/custom          # returns { url, secret, signatureHeader }
POST /v1/cofounder/webhooks/custom           # rotate token + secret
```

**Send an event** — sign the raw JSON body with HMAC-SHA256 using your secret:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
BODY='{"summary":"Support backlog spiked to 40 open tickets","severity":"high","metricPath":"support.backlog"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "https://api.appeeky.com/v1/cofounder/webhooks/custom/$TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Appeeky-Signature: sha256=$SIG" \
  -d "$BODY"
```

Body fields — `summary` (required), plus optional `severity`
(`info`|`low`|`medium`|`high`|`critical`, default `medium`), `appId` (defaults
to your live app), `metricPath`, `fingerprint`, and `magnitude`.

## See also

* [Signals](/concepts/signals) — how signals drive event runs
* [Modes](/concepts/modes) — `proactive_mode` and severity thresholds