PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub
Community appsQuickstartIdentity tokenAPI accessApp webhooksTesting your apppostMessage protocol

API

Community apps

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:

HeaderValue
X-Planeward-Signaturesha256=<hex> HMAC of the raw body, keyed with the signing secret
X-Planeward-DeliveryDelivery id. Dedupe retries on it.
X-Planeward-EventEvent name, same as event in the body.

Verify

Verify against the raw body, before parsing JSON.

app/api/planeward/webhook/route.ts
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

Eventdata
app.installedinstallationId, workspaceId, workspaceName, grantedPermissions, installedAt
app.uninstalledinstallationId, workspaceId, uninstalledAt

Every other event reaches an installation only when it was granted the scope next to it:

EventsScopeSent for
community.membership.granted / complimentary / suspended / resumed / revokedCOMMUNITY_MEMBERS_READEvery membership
community.badge.awarded / revokedCOMMUNITY_MEMBERS_READBadges of any app installed in the workspace
community.message.created / deleted, community.reaction.added / removedCOMMUNITY_MESSAGES_READChannels @everyone can view
community.module.completed, community.course.completedCOURSES_READEvery course
event.registered, event.registration_cancelled, event.attendance_classifiedEVENTS_READEvents with Show in community apps on
form.submittedFORMS_SUBMITPublished 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

Eventdata
community.membership.*id, communityId, customerId, source, status
community.message.createdid, communityId, channelId, replyToId, authorKind, memberId, appInstallationId, authorName, body, createdAt
community.message.deletedid, communityId, channelId, memberId, timestamp
community.reaction.added / removedmessageId, communityId, channelId, emoji, memberId, timestamp
community.module.completedmoduleId, moduleTitle, chapterId, courseId, courseTitle, communityId, memberId, completedAt
community.course.completedcourseId, courseTitle, communityId, memberId, completedAt
community.badge.awarded / revokedbadgeId, badgeKey, appId, memberId, timestamp
event.registered / registration_cancelled / attendance_classifiedid, eventId, contactId, memberId, attendance
form.submittedid, 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.

API access

Call Planeward from your app's backend with the app secret.

Testing your app

Load your dev server inside your own community, then inspect API calls and webhook deliveries.

On this page

EnvelopeHeadersVerifyEventsPayloadsRetries