App webhooks
Signed events sent to your app's webhook URL.
Each app has one webhook URL and one signing secret, set in Settings › Apps › Developer. Events from every installation go to that URL. It must be public HTTPS: localhost and private hosts are refused, even for an app with localhost frame URLs.
Envelope
{
"event": "app.installed",
"data": {
"installationId": "inst_123",
"workspaceId": "ws_123",
"workspaceName": "Harbor Studio",
"grantedPermissions": ["COMMUNITY_MEMBERS_READ"],
"installedAt": "2026-08-25T00:00:00.000Z"
},
"timestamp": "2026-08-25T00:00:00.000Z",
"installationId": "inst_123",
"workspaceId": "ws_123"
}Headers
Same as workspace webhooks:
| Header | Value |
|---|---|
X-Planeward-Signature | sha256=<hex> HMAC of the raw body, keyed with the signing secret |
X-Planeward-Delivery | Delivery id. Dedupe retries on it. |
X-Planeward-Event | Event name, same as event in the body. |
Verify
Verify against the raw body, before parsing JSON.
import {
parsePlanewardWebhook,
PLANEWARD_SIGNATURE_HEADER,
verifyPlanewardWebhook,
} from "@planeward/sdk/server";
export async function POST(request: Request) {
const rawBody = await request.text();
const valid = await verifyPlanewardWebhook({
rawBody,
signature: request.headers.get(PLANEWARD_SIGNATURE_HEADER),
secret: process.env.PLANEWARD_WEBHOOK_SECRET!,
});
if (!valid) return new Response("Invalid signature", { status: 401 });
const envelope = parsePlanewardWebhook(rawBody);
// envelope.event, envelope.installationId, envelope.workspaceId, envelope.data
return new Response(null, { status: 200 });
}verifyPlanewardWebhook compares in constant time and resolves to a boolean. It uses Web Crypto, so it runs on Node 18+ and edge runtimes.
Events
| Event | data |
|---|---|
app.installed | installationId, workspaceId, workspaceName, grantedPermissions, installedAt |
app.uninstalled | installationId, workspaceId, uninstalledAt |
Every other event reaches an installation only when it was granted the scope next to it:
| Events | Scope | Sent for |
|---|---|---|
community.membership.granted / complimentary / suspended / resumed / revoked | COMMUNITY_MEMBERS_READ | Every membership |
community.badge.awarded / revoked | COMMUNITY_MEMBERS_READ | Badges of any app installed in the workspace |
community.message.created / deleted, community.reaction.added / removed | COMMUNITY_MESSAGES_READ | Channels @everyone can view |
community.module.completed, community.course.completed | COURSES_READ | Every course |
event.registered, event.registration_cancelled, event.attendance_classified | EVENTS_READ | Events with Show in community apps on |
form.submitted | FORMS_SUBMIT | Published forms with Show in community apps on |
COURSE_PROGRESS_WRITE also receives the course events, since it allows COURSES_READ. COMMUNITY_MESSAGES_WRITE alone receives no message events.
Events added later may reach your URL as Planeward grows. Ignore an event you don't handle.
Payloads
| Event | data |
|---|---|
community.membership.* | id, communityId, customerId, source, status |
community.message.created | id, communityId, channelId, replyToId, authorKind, memberId, appInstallationId, authorName, body, createdAt |
community.message.deleted | id, communityId, channelId, memberId, timestamp |
community.reaction.added / removed | messageId, communityId, channelId, emoji, memberId, timestamp |
community.module.completed | moduleId, moduleTitle, chapterId, courseId, courseTitle, communityId, memberId, completedAt |
community.course.completed | courseId, courseTitle, communityId, memberId, completedAt |
community.badge.awarded / revoked | badgeId, badgeKey, appId, memberId, timestamp |
event.registered / registration_cancelled / attendance_classified | id, eventId, contactId, memberId, attendance |
form.submitted | id, formId, contactId, memberId, source |
memberId is the member's community membership id, the same memberId the API takes. On message and reaction events it is null when staff or an app acted. On event.* and form.submitted it is the member whose customer has that contact as primary contact, or null when the contact isn't a member.
body is Markdown and can contain mention tokens: @[id] for a person, #[id] for a channel and a literal @everyone. They arrive unresolved, as written. See Channels and messages. There is no webhook for notifications: a mention notifies the member, not your app.
authorKind is member, staff or app. Messages your app posts come back to it too, with authorKind: "app" and your appInstallationId, so skip your own posts to avoid reply loops.
badgeKey and appId tell you which app's badge it is. Check appId against your own app id if you only care about your badges.
App payloads are not the same as workspace webhook payloads. event.* and form.submitted leave out deal (opportunityId) and customer ids, and add memberId. Form answers are not included.
Retries
A failed delivery is retried after 1 minute, 10 minutes, 1 hour and 6 hours. The same delivery keeps its X-Planeward-Delivery id, so store it and skip duplicates.
See every delivery, send a test event and redeliver in the Deliveries tab. See Testing your app.
Planeward Docs