stripe.webhooks.receive

Verify a Stripe webhook, parse the event, and route by event type

Webhook ingress: verify the signature, parse the event, and normalise the fields a downstream grant/fulfilment step needs.

Point a hook redirect at this workflow (dispatch_workflow_type) and Stripe events reach the engine without the app owning an endpoint. The signature is verified against the webhook_secret stored on the connection, so an unsigned or replayed body fails closed before anything acts on it.

This workflow classifies and normalises; it does not itself mutate access. route_workflow_type names the workflow a composition should run next — see stripe.access.grant_on_payment for the payment-to-entitlement chain.

Acts on the CUSTOMER'S OWN Stripe account, authenticated via the org-scoped Stripe connection selected by cloud_connection_uuid.

Inputs:

• cloud_connection_uuid: Org-scoped Stripe connection (customer's own account).
• payload: Raw request body, exactly as received.
• signature: Stripe-Signature header value.
• webhook_secret: Endpoint secret (whsec_...); defaults to the secret on the connection (optional).
• webhook_secret_key: Named key in the connection secrets (optional). A missing named key fails closed (WEBHOOK_SECRET_NOT_FOUND).

Outputs (terminal state_data):

• event_id: str
• event_type: str
• livemode: bool
• route_workflow_type: str — workflow a composition should run next, or None
• object_id: str — id of the event's primary object
• client_reference_id: str — identity carried from checkout, when present
• customer_id: str
• subscription_id: str
• payment_status: str
• event_metadata: json

Connection required: cloud_connection_uuid — the organization's own Stripe account credentials; there is no platform-key fallback.

Overview

Property	Value
Workflow type	Atomic
Library	App-stripe
Version	1.0

Input Schema

Field	Type	Required	Default	Description
cloud_connection_uuid	uuid	Yes	—	Org-scoped Stripe connection (customer's own account)
payload	string	Yes	—	Raw request body, exactly as received
signature	string	Yes	—	Stripe-Signature header value
webhook_secret	string	No	—	Endpoint secret (whsec_...); defaults to the secret on the connection
webhook_secret_key	string	No	—	Named connection secret key; missing key fails closed

Output Schema

Field	Type	Required	Default	Description
event_id	string	No	—	—
event_type	string	No	—	—
livemode	boolean	No	—	—
route_workflow_type	string	No	—	—
object_id	string	No	—	—
client_reference_id	string	No	—	—
customer_id	string	No	—	—
subscription_id	string	No	—	—
payment_status	string	No	—	—
event_metadata	json	No	—	—
cloud_connection_uuid	uuid	No	—	—
payload	string	No	—	—
signature	string	No	—	—
webhook_secret	string	No	—	—
webhook_secret_key	string	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—
failed_layer	integer	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "stripe.webhooks.receive",
  "initial_data": {
    "cloud_connection_uuid": "value",
    "payload": "value",
    "signature": "value"
  }
}