Stripe Events
Goal: Send the Stripe events your licences receive into a data connection, so a surface or a warm query can use them.
A Stripe Events node is a pair: the Stripe event types you pick, and the one data connection they go to. When your workspace's Stripe webhook receives and applies an event of a type you picked, OpenX forwards a small record of it to that connection. It is like an API Source in the other direction: Stripe pushes, and the node carries it onto your canvas.
The node runs nothing in Azure and needs no cloud connection and no landing zone.
Before you start
- A licence with its Stripe keys saved and its webhook set up, so events reach your workspace. See Licenses: the Webhook signing secret is entered in the Stripe connection tab, and the Health tab shows whether the webhook is registered and its secret verifies.
- A data connection to send to. See Connecting Data.
The endpoint you register in your Stripe account is the licence's own address,
https://openx.fathym.com/ox-api/licenses/webhook/<your workspace lookup>/<licence lookup>. The
Licenses API page describes the call and what it answers.
Add one
Drag a Stripe Events node from the Node Bank onto the canvas. It starts switched on and forwards nothing until you pick at least one event type. Click it to open the Inspector.
From any agent connected over MCP, propose it: the agent calls manage_proposals with a StripeEvents record.
The proposal lands in your workspace; you accept it in the portal. The proposal names the event types and the data
connection together, and a type that is not on the list below is refused by name.
Ask Azi: "Send paid and failed invoices to the billing connection." She proposes it; review and accept.
Pick the event types
In the Inspector, the Events tab has one box for each type your licences' webhook applies: "The Stripe events to forward to the wired data connection. Nothing is forwarded until at least one is chosen."
| Event type | When Stripe sends it |
|---|---|
checkout.session.completed | A buyer finishes a Checkout |
customer.subscription.created | A subscription starts |
customer.subscription.updated | A subscription changes (plan, price, status) |
customer.subscription.deleted | A subscription ends |
customer.subscription.paused | A subscription is paused |
customer.subscription.resumed | A paused subscription resumes |
customer.subscription.trial_will_end | A trial is about to end |
invoice.paid | An invoice is paid |
invoice.payment_failed | A payment fails |
Matching is exact and case-sensitive. Those nine are the only types the webhook applies, so they are the only ones
a node can ask for. Save refuses anything else with STRIPE_EVENTS_EVENT_TYPE_UNKNOWN, naming the type and the
list, whether you ticked it in the Inspector or an agent proposed it. An empty choice forwards nothing.
Wire it to a data connection
Draw a line from the node's right-hand handle to a data connection. The line is labelled forwards. A node
forwards to one connection; to send the same events to two, use two nodes. An agent sets the same thing with the
record's DataConnectionLookup.
Every connection OpenX makes is an Azure IoT Hub device connection, which is what the node can send to. A node with event types but no connection, or one that points at a connection that does not exist, forwards nothing, and its failed forwards show on its Status tab.
What each forwarded event carries
Each applied event of a picked type goes to the wired connection as one small record, with no personal data:
{
"EventID": "evt_...",
"Type": "invoice.paid",
"Created": "2026-10-23T08:55:10.000Z",
"WorkspaceLookup": "your-workspace",
"LicenseLookup": "my-licence",
"ObjectID": "in_...",
"ObjectStatus": "paid"
}
| Field | Meaning |
|---|---|
EventID | Stripe's id for the event |
Type | The event type |
Created | When Stripe created the event |
WorkspaceLookup | Your workspace |
LicenseLookup | The licence whose webhook received it |
ObjectID | The id of the subscription, invoice or checkout session the event is about |
ObjectStatus | That object's status, such as active, paid or complete |
A field Stripe did not send is left out. The raw Stripe payload is never forwarded: no customer, email, name, address or card, and an id or status is passed only if it is plain Stripe-token text.
Only an event that was applied is forwarded. A repeat Stripe sends again, a type outside the list above and a call that failed verification are not.
Delivery
The forward never holds up Stripe's answer. If a send fails, it is tried up to three times over about ten seconds; after that it is logged, the node's Last Error is set, and it is not sent again later.
Status
The node shows three tiles, and the Inspector's Status tab shows the same:
| Tile / row | What it is |
|---|---|
| Forwarded | How many events this node has forwarded to its connection |
| Last Forwarded | When the last one went. It turns red only while the last failure is newer than it |
| Last Error | When the last forward failed after its retries, or was skipped for want of a usable connection |
A value that has not happened yet shows —, never a zero. A quiet node is not red for being quiet, and an old
error after a later success is healthy. An agent reads the same three with get_stats for the StripeEvents kind.
To see what your workspace received, whether or not a node picked it, open Licenses -> Manage Licenses and
its Events tab, "Stripe events received": each licence's recent events (type and time) with the verified and
refused counts for the last 24 hours. The same read is GET /ox-api/licenses/events in the
Licenses API. It needs Licenses.Read.
Switch it off, or remove it
The Active switch (the node's toggle) stops forwarding and deletes nothing; switch it on to resume. Events that arrive while it is off are not held back.
To remove the node, select it, press the delete icon (tooltip Delete Node) and Save. Nothing of it runs in Azure, so there is nothing to Deploy. Removing it stops forwarding: "Your Stripe account, its webhook and the data connection stay." See Removals.
If nothing arrives
- Is the node Active and does it have at least one event type?
- Is it wired to a data connection that still exists?
- Does the licence's Health tab show the webhook registered and its secret working, and does the Events tab show the event type arriving?
- Is the type on the list above? Stripe must send that exact type to your licence's webhook address.
Next steps
- Use the events -> Surfaces and Warm Queries
- The webhook and the reads -> Licenses API
- Setting up what you sell -> Licenses