plan.created
A plan is first created on a project.
When this fires
A plan is created through the REST API (POST /v1/projects/{project}/plans) or the create_plan MCP tool, or a finished pass season is duplicated into its next season. Plans created from the creator dashboard or the bot do not emit this event. The plan is immediately eligible for purchase if it was created in the active state.
The two shapes are disjoint. The API and MCP path sends
data.planand nothing else; the season-duplication path sends the four flat keys and nodata.planobject. Branch on whetherdata.planordata.plan_idis present before reading any other field.
billing_cycle is only the unit. The multiplier lives in billing_cycle_count on the plan record and is not included in this payload: a "3 month" plan sends billing_cycle: "month" with no indication of the 3. Nor is trial_days. Fetch the plan with GET /v1/projects/{project}/plans/{plan} when you need the full cadence or trial configuration.
Caveats
- A
plan.createdevent does not imply the plan has been synced to a payment-provider catalog. Listen forplan.sync_completedfor that. - Trial is configured at create time. A later trial-only edit is only applied, and only then fires
plan.updated, when the PATCH also carries akindkey; without it the trial fields are dropped and no event is emitted.
Related events
plan.updated: subsequent edits.plan.sync_completed: provider catalog sync.
Header Parameters
t=<unix seconds>,v1=<hex>: the HMAC-SHA256 of "<t>.<raw body>" under the endpoint's secret. Verify it before acting, and refuse a t more than 300 seconds from now. During a secret rotation a v0= signature under the previous secret may precede v1=.
The event's ULID, bare. The envelope's id is the same ULID prefixed evt_, so strip the prefix before comparing. Deduplicate on it: a retry carries the same id.
The event name, the same as the envelope's type.
Always application/json.
Always Subscriby-Webhooks/1.0.
Request Body
application/json
The signed JSON envelope posted to your endpoint.
TypeScript Definitions
Use the request body type in TypeScript.
The envelope every event is delivered in.
Response Body
Example Requests
/plan.createdHow is this guide?