All pages
Webhooks
craving POSTs every app lifecycle and Resident event to the webhook URL configured under Connection > Webhook on your app page, signed with X-Craving-Signature (Authentication). Return a 2xx status within 10 seconds and process heavy work asynchronously.
Every webhook payload includes event, app_id and sent_at.
| Event | Payload fields | When it fires |
|---|---|---|
installation.created | installation_id, scope, agency_id, installer, granted_scopes, plan_id, install_code, install_code_expires_at | A Resident or agency activated your app. Exchange install_code within 10 minutes. |
installation.updated | installation_id, plus status (reason), settings or granted_scopes | Settings changed, a paid install settled or paused (refund / payment_due), or the installer approved new permissions. |
installation.uninstalled | installation_id, scope, delete_data_by | The app was removed. All tokens are revoked; delete installation data within 30 days (usage events remain open for 24 hours). |
block.placed / block.removed | installation_id, block_id, landing_id | Your Home block was added to or removed from a Home. |
review.decided | version_id, version, status (live or rejected), reason, checks | A submitted version was approved or rejected. |
app.suspended / app.restored | reason | An admin suspended or restored your app. |
support.opened / support.message | thread_id, subject (on support.opened) | An installer opened or replied to a support thread; reply from Support on your app page. |
channel.connected | installation_id, channel_id, external_id | A Resident connected an external account to your channel connector. |
ping | dry_run: true or test: true | Automated review check, or a manual test sent from the Webhook sheet. |
Resident events
In addition to app lifecycle events, your app can subscribe to activity around the Residents who installed it. Declare the event kinds you want in your manifest’s events array; installers see and approve them on the consent sheet alongside scopes.
Resident events are aggregated over a time window per Resident and event kind, so a Resident who makes 40 sales in 15 minutes produces one webhook delivery rather than 40. The payload reports the count, summed amounts and up to 20 subject references:
{
"event": "visitor.purchase",
"app_id": "…",
"sent_at": "2026-09-13T20:15:00Z",
"installation_id": "…",
"creator_id": "…",
"count": 3,
"batches": 1,
"first_at": "2026-09-13T20:01:12Z",
"last_at": "2026-09-13T20:14:05Z",
"subjects": ["fan_4f1c…", "fan_9a02…"],
"facts": { "cents": 4700 }
}count: total events folded into this delivery.batches: number of aggregation windows combined (greater than1when deliveries were held past the daily quota).subjects: up to 20 references to the Visitors (fan_…, matching chat toolfan.refandGET /v1/fans/{ref}) or Homes involved.facts: summed numeric totals for the window.creator_id: the Resident the events belong to (agency installations receive one delivery per managed Resident).
home.review_decided- A review of one of their Homes came back: approved, or refused with the reason on the Home. Needs
home.read· at most once per 15 min · subjects: Home ids · facts:approvedrefused visitor.purchase- A Visitor paid them: a tip, content, a call, a request or a membership. Needs
earnings.read· at most once per 15 min · subjects: Visitor refs · facts:cents request.created- A Visitor sent a personal request. Needs
fans.read· at most once per 15 min · subjects: Visitor refs · facts:cents visitor.new- Someone reached out to them for the first time. Needs
fans.read· at most once per 15 min · subjects: Visitor refs visitor.message- Visitors wrote to them, counted per Visitor; never the words. Needs
chat.read· at most once per 15 min · subjects: Visitor refs visitor.lapsed- A paying Visitor went quiet: no purchase and no message in thirty days. Needs
fans.read· at most once per 1 h · subjects: Visitor refs membership.started- A Visitor started a membership with them. Needs
fans.read· at most once per 15 min · subjects: Visitor refs · facts:cents membership.payment_failed- A member's renewal payment failed; the membership is past due. Needs
fans.read· at most once per 15 min · subjects: Visitor refs · facts:cents
Each installation receives up to 1,000 Resident event deliveries per Resident per UTC day.
Any further batches that day are held and collapsed into a single delivery per event kind the next day (batches reflects how many windows were combined). You can inspect today’s quota usage and the last 7 days of deliveries in the Webhook sheet on your app page. Adult apps only receive events for 18+ accounts.
Delivery and retries
Deliveries that time out (after 10 seconds) or return a non-2xx status retry with exponential backoff: 1 minute, 4 minutes, 16 minutes, 64 minutes, and then every 24 hours, up to 8 attempts total. If your endpoint returns 429 with Retry-After, craving waits at least that many seconds before the next attempt. After 8 failed attempts, the delivery is marked failed.
Deliveries can arrive out of order or more than once. Deduplicate by installation_id and the event’s identifiers (for Resident events, (installation_id, event, creator_id, last_at)).