Self-improving AI Employees for everyone
Stripe Receive (stripeReceive)
| Field | Value |
|---|---|
| Category | payments / trigger (class group = ("payments", "trigger")) |
| Backend handler | server/nodes/stripe/stripe_receive.py (StripeReceiveNode, on WebhookTriggerNode); daemon + webhook plumbing in _source.py (StripeListenSource, StripeWebhookSource, shape_stripe_event); the CloudEvents factory and deployed-path emit in _events.py; framework base services/events/triggers.py, services/events/webhook.py, verifier services/events/verifiers/stripe.py |
| Tests | server/tests/nodes/test_stripe_plugin.py, TestTriggerPrepareDeployment in server/tests/test_deployment_canary_listener.py |
| Skill (if any) | none as a tool (the stripe-skill teaches it in prose; its allowed-tools names only stripe_action) |
| Dual-purpose tool | no (trigger) |
Purpose
Fire a workflow when Stripe delivers a webhook event, on a canvas Run and in a
deployed workflow. A supervised stripe listen daemon forwards every event for
the logged-in account to POST /webhook/stripe; the source verifies the
Stripe-Signature header against the whsec_ secret captured from the
daemon's own stderr, flattens the Stripe event into the trigger's output
(shape_stripe_event), and wraps it in one WorkflowEvent type,
com.opencompany.stripe.event.received, with the Stripe type in subject and
data.event_type. It hands that envelope to the in-process event waiter (a
canvas Run, or a deploy that runs without Temporal) and to
services.events.dispatch.emit (deployed listeners on Temporal). The node
contributes the event-type and livemode filter, the daemon start (on a canvas
Run and on deploy), and the output unwrap.
Inputs (handles)
None - this is a trigger; it is the head of a run.
Parameters
StripeReceiveParams(BaseTriggerParams), extra="ignore".
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
event_type_filter |
string | all |
no | - | all, an exact Stripe type (charge.succeeded), or a prefix.* glob (charge.*). Matched against data.event_type; a leading stripe. is accepted and stripped, for patterns written when the node required it |
livemode_filter |
all | test | live |
all |
no | - | Compared with data.livemode: live admits live-mode events only, test test-mode events only |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | StripeReceiveOutput: the shaped event (shape_stripe_event), identical on a canvas Run and in a deployed run |
Output payload (TypeScript shape)
extra="allow". All fields are Optional on the model.
{
event_id: string; // Stripe's evt_ id ("" when the payload had none)
event_type: string; // Stripe's type, e.g. "charge.succeeded" ("unknown" when missing)
created: number | null; // Stripe's created (Unix seconds)
livemode: boolean | null;
api_version: string | null;
request_id: string | null; // request.id, or request when Stripe sends a bare value
account: string | null; // set only for Connect events
data: object; // Stripe's data object {object, previous_attributes?}, {} when missing
}
Logic Flow
flowchart TD
L[stripe listen daemon: binary listen --forward-to http://localhost:PYTHON_BACKEND_PORT/webhook/stripe --print-secret] -- stderr whsec_ --> K[store_api_key stripe_webhook_secret]
L -- forwards --> W[POST /webhook/stripe]
W --> V{StripeCredential.resolve -> stripe_webhook_secret}
V -- missing --> R503[503 + Retry-After 5]
V -- ok --> H[StripeVerifier: t= and v1= HMAC-SHA256 hex over t.body]
H -- header missing / mismatch --> R400[400]
H -- ok --> J[json.loads body] -- invalid --> R400
J --> S[shape_stripe_event -> stripe_event_received: id=evt id, type=com.opencompany.stripe.event.received, subject=Stripe type, data=shaped event]
S --> D1[event_waiter.dispatch envelope]
S --> D2[emit_stripe_event -> dispatch.emit]
D1 --> RUN[canvas Run waiter keyed on the same type: build_filter on data -> resolve -> shape_output unwraps data]
D2 --> DEP[deployed listener, EventType = that type: evaluate_trigger_filter_activity runs build_filter on data -> run starts with data as the trigger output]
subgraph canvas Run
P[_check_precondition: start stripe listen if needed] --> RUN
end
subgraph Start and boot re-arm
PD[prepare_deployment: start stripe listen in the background] --> DEP
end
Decision Logic
- One CloudEvents type: every Stripe event is
com.opencompany.stripe.event.received. A deployed trigger listens for exactly one type (register_canary_trigger_typerecords one string per node type, and the listener'sEventTypeSearch Attribute and the controller'son_eventmatch it exactly), so per-event types such asstripe.charge.succeededcould never reach a deployedstripeReceive. The node setsevent_typeto the same constant, which keys the canvas-Run waiter. - Two delivery paths:
WebhookSource.handledispatches into the in-process event waiter, which serves a canvas Run and the deploy path without Temporal: the deployment manager arms the in-process collector instead of a Temporal listener when no Temporal client is connected (TEMPORAL_ENABLED=false, or Temporal not up yet) or the event framework is off.StripeWebhookSource.handlethen callsemit_stripe_event, which reaches deployed listeners on Temporal. The envelope carries noworkflow_id, so every deployment with the trigger receives it. - Filter (
build_filter): both callers pass the envelope'sdata(the waiter andevaluate_trigger_filter_activity); an envelope is accepted too.event_type_filteris matched againstdata.event_typewithevent_type_matches(exact, orprefix.*;all/ empty matches everything);livemode_filtercomparesbool(data.livemode). A payload that is not a dict is rejected. - Output: shaped once, in the source, because a deployed trigger hands
downstream nodes
event.dataverbatim;shape_outputreturns that samedata, so a canvas Run and a deployed run see the same fields. - Daemon start:
- Canvas Run (
_check_precondition): if the listen source is not_started,has_credential()(a filesystem sniff for_api_keyin the CLI'sconfig.toml) must be true, else the run returns "Stripe not connected. Log in with Stripe in Credentials."; a failed start returns "Stripe daemon failed to start: ". - Deploy (
prepare_deployment, called byDeploymentManager._prepare_trigger_deploymentat Start and when the boot re-arm restores a running or paused generation): the same start, in a background task so a first-use CLI download never holds up Start. A failure or a missing login is logged as a warning and the trigger stays armed; logging in with Stripe starts the daemon, and events flow from then on. - The status refresh never starts the daemon.
- Canvas Run (
- Signature verification fails closed: no captured secret -> HTTP 503
with
Retry-After: 5; missing header, missingt=/v1=, or no matchingv1=candidate -> HTTP 400. Multiplev1=values are accepted (rotation). - Fallbacks:
createdmissing or non-integer ->time = now(UTC); missingid-> emptyevent_id; missingtype->event_type = "unknown";datanot a dict ->{};accountabsent ->null, and the envelope'ssourceisstripe://default.
Side Effects
- Subprocess: the
stripe listendaemon (StripeListenSource,process_name = "stripe-listen",workflow_namespace = "_stripe", cwd<DATA_DIR>/daemons/), supervised byProcessService, which logs its stdout / stderr and broadcasts them to the Terminal tab.--forward-tousesSettings().port(PYTHON_BACKEND_PORT). - Database writes:
auth_service.store_api_key("stripe_webhook_secret", <whsec_...>, models=[])whenever awhsec_token appears on the daemon's stderr (fire-and-forget task). - Event dispatch:
event_waiter.dispatchanddispatch.emit(wire routing keystripe_event_receivedfor the in-process broadcast half ofemit) for every verified delivery. - Broadcasts: none of its own on a canvas Run (
TriggerNode.executeregisters the waiter without awaitingstatus; the generic trigger handler inservices/handlers/triggers.pythat sends one serves onlytwitterReceive). A deployed trigger showswaitingfrom the deployment manager (Temporal listener) or the in-process collector.make_status_refreshmirrorssource.status()(type/running/pid, without login state) intobroadcaster._status["stripe"]once at startup and broadcasts it asstripe_status, which no frontend code handles. - HTTP:
POST /webhook/stripeanswered by the router afterhandle(); the source'sreceive()also enqueues the event on its internal push queue (nothing consumes that queue for this source). - WS handlers:
stripe_connect/stripe_disconnect/stripe_reconnect/stripe_status(lifecycle factory,stripe_statusoverridden to addlogged_in/connected),stripe_login,stripe_logout,stripe_trigger.
External Dependencies
- Credentials:
StripeCredential(id = "stripe",auth = "custom") -resolve()exposes onlystripe_webhook_secret; login state is the CLI's ownconfig.toml($XDG_CONFIG_HOME/stripe/or~/.config/stripe/). - Services: the Stripe CLI (system PATH preferred, else pinned
1.40.9download into<DATA_DIR>/packages/stripe/bin/); Stripe's webhook delivery throughstripe listen. - Python packages:
pydantic, stdlibhmac/hashlib,fastapi. - Environment variables:
PYTHON_BACKEND_PORT(viaSettings().port),XDG_CONFIG_HOME.
Edge cases & known limits
TRIGGER_START_TO_CLOSE(24 h) bounds the Temporal activity for a canvas Run; there is no shorter wait timeout.- Redeliveries keep Stripe's
evt_id as the envelope id, so a deployed listener drops a redelivery as a duplicate; a canvas Run resolves once anyway. - Secret race: events forwarded before the
whsec_line is captured get a 503 and are retried by Stripe / the CLI. - One account per install; the daemon is a single global process.
- No auto-restart on daemon crash, and nothing reports it: the source's
_startedflag is cleared only bystop(), sostripe_statusstill saysrunning: true, the precondition and the deploy hook both skip the start, and the Credentials modal still shows Stripe as connected. Disconnect, then Login with Stripe, restarts it. - No hire uses
stripeReceiveas a trigger yet:config/employee_apps.jsonkeeps Stripe a tool-only app.
Related
- Sibling:
stripeAction(trigger <event>is the easiest way to exercise this node) - Architecture docs: Stripe Service, Event Waiter System, Event Framework