PlanewardPlaneward Docs
PlanewardPlaneward Docs
Welcome

Developers

REST APIAuthenticationWebhooksMCPEmbedded projectsTask description contentDeveloper hub

API

Webhooks

Outbound signed deliveries, event catalog, and URL rules.

Create endpoints in Developer → Webhooks. HTTPS URLs only. Private, loopback, and link-local hosts are rejected (SSRF protection).

To receive a POST into a workflow (not this outbound catalog), use an inbound webhook trigger.

Envelope

Deliveries POST JSON:

{
  "event": "project.created",
  "data": {},
  "timestamp": "2026-08-25T00:00:00.000Z"
}

Signature

Verify X-Planeward-Signature as sha256=<hex hmac of the raw body> using the endpoint signing secret. The secret is shown once at create (or when you rotate it).

Headers

HeaderValue
X-Planeward-Signaturesha256=<hex> HMAC of the raw body
X-Planeward-DeliveryDelivery id, unique per endpoint and event. Dedupe retries on it.
X-Planeward-EventEvent name, same as event in the body, for routing before parsing.

Test event

Send test event on an endpoint delivers to that endpoint only. No other endpoint and no workflow sees it. The body is a project.updated sample with test: true at the envelope root:

{
  "event": "project.updated",
  "data": {
    "id": "project_1",
    "old": { "name": "Website refresh" },
    "new": { "name": "Website redesign" },
    "changes": ["name"]
  },
  "timestamp": "2026-10-29T00:00:00.000Z",
  "test": true
}

Live deliveries have no test key. The response shows up under Deliveries. The test event is not a subscription.* event, so Subscription events: community plans only does not affect it.

Events

An empty subscription list means every catalog event, except the community chat events below, which an endpoint only gets when it lists them.

  • project.created / updated / deleted
  • task.created / updated / deleted
  • customer.created / updated / deleted
  • contact.created / updated / deleted / unsubscribed / dm_opt_out / marketing_consent / merged
  • pipeline.created / updated / deleted
  • opportunity.created / updated / stage_changed / deleted
  • sequence.enrolled / stopped / paused / resumed / completed
  • event.registered / registration_cancelled / attendance_classified
  • form.submitted
  • funnel.started / step_viewed / completed
  • invoice.created / updated / deleted / finalized / paid / due / overdue
  • payment.created / updated / completed / refunded
  • expense.created / updated / deleted / adjusted / budget_exceeded
  • channel.created / updated
  • message.created / updated / deleted
  • instagram.message.received, instagram.comment.created
  • email.delivery.sent / failed / opened / clicked / bounced / complained, email.campaign.completed
  • community.membership.granted / complimentary / suspended / resumed / revoked
  • community.receipt.submitted / approved / rejected
  • subscription.started / renewed / completed / cancel_scheduled / canceled / expired / terminated / renewal_upcoming
  • community.course.published
  • community.waitlist.joined, community.waitlist.accepted, community.waitlist.rejected
  • community.module.completed, community.course.completed
  • community.badge.awarded / revoked
  • community.message.created / deleted, community.reaction.added / removed — opt-in only

Every event's data has a fixed schema. planeward-workflow-node-types returns the JSON Schema for each one, and the workflow editor shows a sample.

opportunity.stage_changed data includes previousStageId, stageName, and stageType (OPEN, WON, LOST). contact.unsubscribed data includes contactId and source (unsubscribe_link, manual, or complaint). Community membership and receipt data include communityId and customerId. The receipt and waitlist events come from Commerce, so they fire for a workspace with no community too; their keys keep the community. prefix, and communityId is null when there is no community (receipts also when the plan is not linked). community.waitlist.accepted only unlocks the plan for checkout; it gives no membership. The subscription.* events below fire for every plan. community.waitlist.joined fires when someone joins a waitlist; applying again (including after being rejected) fires nothing. community.waitlist.accepted fires when an entry is accepted: by staff, by the Accept waitlist entry workflow action, or automatically on a product whose plans are all free. community.waitlist.rejected fires when staff or the Reject waitlist entry workflow action reject an entry.

task.created data is id, projectId, parentId, title, statusId, priority, startDate, dueDate, and completedAt. task.deleted is id, projectId, parentId, and title. message.created is id, channelId, threadParentId, authorMembershipId (null for API-posted messages), authorName, body, and createdAt.

Community chat events

community.message.* and community.reaction.* are not part of every event. Select them on the endpoint to receive them. They can be frequent and carry message text.

Eventdata
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

authorKind is member, staff or app. memberId is the member's community membership id, or null when staff or an app acted. appInstallationId is set when an app posted.

Course, badge and registration events

Eventdata
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.registration_cancelledid, eventId, contactId, opportunityId, attendance, same as event.registered

event.registered also fires when a payment for a product linked to the event registers the buyer, and event.registration_cancelled when a refund that ends the buyer's plan removes that seat. See Paid events.

community.badge.* fires when a community app awards or revokes one of its badges. community.course.completed fires with the module completion that finishes a course, at most once per member and course.

Subscription lifecycle

subscription.* events fire for every plan, whether Stripe, Xendit, or manual, with or without a community. An endpoint subscribed to every event (an empty list) starts receiving them too.

EventFires when
subscription.startedThe first paid activation, a rejoin after the previous subscription ended (its status was not ACTIVE), or a staff grant (complimentary is true)
subscription.renewedA continuing paid cycle on a subscription that was already ACTIVE
subscription.completedSubscription fully paid: a payment reached the plan's cycle cap. Sent alongside that payment's started or renewed, and may arrive before it
subscription.cancel_scheduledThe member or the processor set the subscription to cancel at period end. It stays ACTIVE until periodEnd
subscription.canceledThe processor stopped billing: the Stripe subscription was deleted, or the Xendit plan was inactivated. Staff revoking a grant sends it too. Not sent for a subscription that already expired
subscription.expiredThe paid period ran out, or a Xendit cycle failed after the period ended. Checked hourly: Stripe and Xendit plans still renewing expire 72 hours after periodEnd so the processor can collect; manual plans and plans set to cancel expire at periodEnd
subscription.terminatedA refund or chargeback ended the subscription immediately
subscription.renewal_upcomingA set time before the period ends; see Workflows

Lifecycle data is id, customerId, customerName, customerEmail, productId, productName, productPlanId, planName, price (minor units, 2900 is $29.00), currency, interval, intervalCount, communityId, status, previousStatus, periodEnd, cancelAtPeriodEnd, managedBy (MANUAL, STRIPE, or XENDIT), and complimentary. started and renewed also send paidCycles and maxCycles; completed sends paidCycles, maxCycles, and lifetimeAfterFinalCycle. customerEmail, communityId, previousStatus, and periodEnd can be null.

complimentary is true for a staff grant: free, lifetime access with no payment. A grant sends subscription.started with managedBy MANUAL, paidCycles 0, and periodEnd null, and revoking it sends subscription.canceled. To act only on paid starts, check that data.complimentary is false. Payments never land on a grant and refunds never end it: a later payment for the same plan starts or continues a paid subscription of its own, with its own events and complimentary false.

communityId is set for plans of products that grant community access and null for every other plan. To handle only community plans, turn on Subscription events: community plans only on the endpoint, check that data.communityId is not null in your endpoint, or in a workflow add a field condition on communityId with Not empty.

Community plans only

Subscription events: community plans only is an endpoint setting (off by default) shown when the endpoint gets every event or any subscription.* event. When it is on, the endpoint gets subscription.* events only when data.communityId is set, so plans without a community, and their customers' names and emails, never reach it. Every other event is delivered as usual, and the setting never adds an event the endpoint did not choose. Change it under the endpoint's Settings tab.

Migrating from community.subscription.* (2026-11-05)

The community.subscription.* events are removed. Endpoints subscribed to them were switched to the matching subscription.* event, and now receive the full lifecycle data above (including customerName and customerEmail) instead of the old community payload. Remapped endpoints are set to community plans only, so they still get community plans only; turn it off to receive every plan. An endpoint that already listed a subscription.* event was already receiving every plan, so it was left off.

RemovedReplacement
community.subscription.startedsubscription.started
community.subscription.renewedsubscription.renewed
community.subscription.expiredsubscription.expired
community.subscription.completedsubscription.completed

A rejoin (the subscription ended, then was paid again) now sends subscription.started, not renewed. subscription.* also fires for plans without a community; with community plans only off, skip events where communityId is null if you only want community plans.

Updated events

Breaking change (2026-10-29)

Every *.updated event now sends only what changed, as old, new, and changes. Fields are no longer at the top level of data. Read data.new.<field> where you used to read data.<field>.

Every *.updated event sends the same shape:

KeyValue
idThe record that changed
parent idsThe ids that scope it, such as projectId on a task (see below)
oldPrevious values of the changed fields only
newNew values of the changed fields only
changesNames of the changed fields; never empty

Unchanged fields are left out of old and new. An update that changes nothing sends no event. Dates are ISO strings and money is integer minor units.

Before, a task moved to Done sent the record's summary and you had to fetch the task to see what changed:

{
  "event": "task.updated",
  "data": {
    "id": "task_1",
    "projectId": "project_1",
    "title": "Draft homepage copy"
  },
  "timestamp": "2026-10-29T09:30:00.000Z"
}

Now:

{
  "event": "task.updated",
  "data": {
    "id": "task_1",
    "projectId": "project_1",
    "old": { "statusId": "status_todo", "completedAt": null },
    "new": {
      "statusId": "status_done",
      "completedAt": "2026-10-29T09:30:00.000Z"
    },
    "changes": ["statusId", "completedAt"]
  },
  "timestamp": "2026-10-29T09:30:00.000Z"
}
EventParent idsFields that can appear in old / new
project.updated—name, description, color, icon, categoryId, archivedAt, canvasEnabled, doneTaskArchiveAfterDays
task.updatedprojectIdtitle, description, statusId, priority, parentId, milestoneId, cycleId, storyPoints, startDate, dueDate, startAt, dueAt, completedAt, archivedAt, labelId, assigneeMembershipIds, assigneeRoleIds
customer.updated—name, email, phone, address, company, role, socialLinks, tags, lifecycleStatus, nextFollowUpAt, hourlyRate, typeIds
contact.updatedcustomerIdname, email, phone, role, customerId, tags, emailMarketingOptOut, marketingConsentAt, guardianEmail, guardianConsentAt, dmOptOutAt
pipeline.updated—name
opportunity.updatedpipelineId, contactIdname, stageId, contactId, customerId, value, ownerMembershipId, nextFollowUpAt, qualFit, qualTimeline, qualBudget, qualDecisionMaker, qualAge, closeReason, closeNote, nurtureReason, closedAt
invoice.updatedcustomerIdcustomerId, title, memo, amount, discountType, discountPercentage, discountAmount, shipping, items, taxes
payment.updatedcustomerIdcustomerId, amount, status, paidAt, note, reversedAt
expense.updatedcategoryIdamount, spentAt, description, vendor, notes, categoryId, receiptFileAssetId, deletedAt
channel.updatedcategoryIdname, description
message.updatedchannelIdbody

On task.updated, assigneeRoleIds is a sorted list of role ids. You also get this event when a role is taken off a task because it can no longer be assigned in the project. See assigning roles.

Parent ids show the record's current value. When a parent id itself changes (a contact moved to another customer), it also appears in old, new, and changes.

Deliveries stop while the endpoint is paused.

Authentication

API keys, headers, prefixes, and scopes.

MCP

Streamable HTTP MCP for Claude, ChatGPT, editors, and any MCP client.

On this page

EnvelopeSignatureHeadersTest eventEventsCommunity chat eventsCourse, badge and registration eventsSubscription lifecycleCommunity plans onlyUpdated events