All pages
Quickstart: a drawn block
The shortest way to a live app is a drawn block: your server answers a small JSON document, and craving draws it on the Resident’s Home with the Home’s own components, on the web and in the app. There is no iframe, no session token to verify and no token exchange. Your server needs two endpoints on one https origin: the webhook and the block’s content.
1. Apply and create the app
Apply as a developer and create the app in craving Apps, then complete its Listing (Getting started, steps 1 and 2).
2. Answer craving
Every request craving sends is signed with your webhook secret (shown once when you set the webhook under Connection > Webhook). This server verifies the signature, answers the webhook with 204, and answers the block’s content with a document built from the Resident’s settings:
import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = process.env.CRAVING_WEBHOOK_SECRET!;
function signed(rawBody: string, header: string | undefined): boolean {
const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.trim().split('=')));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = createHmac('sha256', SECRET).update(`${parts.t}.${rawBody}`).digest('hex');
const given = Buffer.from(parts.v1 ?? '');
return given.length === expected.length && timingSafeEqual(given, Buffer.from(expected));
}
createServer(async (req, res) => {
let raw = '';
for await (const chunk of req) raw += chunk;
if (req.method !== 'POST' || !signed(raw, req.headers['x-craving-signature'] as string)) {
return res.writeHead(401).end();
}
const body = JSON.parse(raw);
if (req.url === '/craving/webhook') {
// installation.created, installation.uninstalled, ping, ...
return res.writeHead(204).end();
}
if (req.url === '/craving/block') {
const city = body.settings.city;
res.writeHead(200, { 'content-type': 'application/json' });
return res.end(
JSON.stringify({
format: '1',
items: [
{ type: 'text', text: `This week in ${city}`, size: 'lg' },
{
type: 'row',
title: 'Open studio',
subtitle: `Workshop space, ${city}`,
date: '2031-05-02T20:00:00',
action: { type: 'open_url', url: 'https://app.example.com/events/1', label: 'Tickets' },
},
{ type: 'button', label: 'Notify me', action: { type: 'subscribe' } },
],
}),
);
}
res.writeHead(404).end();
}).listen(8787);The request to your content endpoint carries installation_id, block_id and settings; the document’s items, their limits and the actions are on Home blocks. subscribe is craving’s own email form: the Visitor becomes the Resident’s lead, and you are told nothing.
3. Write the manifest
In Versions, tap New version and save:
{
"manifest_version": "1",
"capabilities": ["home_block"],
"scopes": [],
"origins": ["https://app.example.com"],
"block": {
"render": "json",
"content_url": "https://app.example.com/craving/block",
"refresh_seconds": 3600,
"settings_schema": [{ "id": "city", "type": "text", "label": "City", "default": "Ghent" }]
}
}The Resident fills settings_schema as a form, and their answers arrive in settings. A drawn block asks for no scope, so the consent screen stays empty. Set the webhook to https://app.example.com/craving/webhook.
4. See it on your Home
Run the server behind a tunnel (Cloudflare Tunnel, ngrok) whose origin is the one in origins, install your draft from its preview listing and turn on On your Home (Test installs). craving fetches the content when the block is placed or its settings change, then again once it is older than refresh_seconds; when your content changes sooner, call POST /v1/blocks/refresh (the one step here that needs an install token: Getting started, step 5).
5. Submit
Submit for review. A version with no heavy scope goes live as soon as every automated check passes; a failed check names its requirement on Listing requirements.
Next
- A UI of your own: a framed block (Home blocks).
- Answers in a Resident’s chats: Chat tools.
- Charging for the app: Billing and payouts.