Webhook Sentinel (Stripe) v1.1.0

The webhook signing secret associated with your Stripe Webhook. Find this in the Stripe Dashboard under Developers → Webhooks → Your endpoint → Signing secret. Always starts with "whsec_". Never expose this value in client-side code or logs.

The Stripe-Signature header sent by Stripe with every webhook request. In Bubble, use Event Request Data's headers stripe-signature.

The raw body string of the incoming request. In Bubble, use Event Request Data's raw body text. Must be the original unmodified body, any parsing or reformatting will cause the signature verification to fail, even if the request is legitimate.

Tolerance in seconds for validating the event timestamp. Events older than this value are rejected to prevent replay attacks. Defaults to 300 (5 minutes), which is the same tolerance Stripe's own libraries use. The minimum is 30 seconds and lower values are raised to it on purpose: Stripe documents a tolerance of 0 as a common mistake, because it turns the recency check off entirely. Increase only if your server has known clock sync issues, and prefer fixing the clock with NTP, which is what Stripe recommends.

The 30 second floor is not arbitrary: Stripe lists a tolerance of 0 as a common mistake, because it turns the recency check off entirely. If events are being rejected as expired, fix the server clock with NTP rather than raising this value, which is also what Stripe recommends.

Turns on the livemode check. Off by default, and off means the environment is not verified at all. When it is on, [Accept events from the live version] must have a value, otherwise every event is rejected with rejection_reason "livemode_check_misconfigured". The environment is read from inside the signed payload, so it cannot be forged. This does not replace the separation the signing secrets already provide, since the test and live endpoints have different secrets: it is the net for when the same secret ends up configured in both environments.

The plugin reads the environment from inside the signed event and compares it with this field. Yes accepts only live events, no accepts only test events, and a test version includes any development branch. Point it at Bubble's own Isn't live version with is "no" to build an environment check that compares the two modes, the event's and the app's, so the check follows your deploys. Pointing it at Isn't live version alone inverts the answer and rejects every real event. Only read when [Enable livemode check] is on.

Turns on the IP allowlist check. Off by default, and off means this action behaves exactly as it did before: only the signature, the timestamp and the environment are verified. When it is on, both [IP allowlist] and [Request IP] must be filled, otherwise every event is rejected with rejection_reason "ip_check_misconfigured". That is deliberate: a security check you turned on and left unconfigured should fail loudly, not pretend to protect you.

The IP addresses allowed to deliver webhooks, one per line or separated by commas. Comes pre-filled with the list Stripe published when this plugin version was released. That list is a snapshot, not a live feed: check https://stripe.com/files/ips/ips_webhooks.json before relying on it. Stripe changes these addresses over time, and an address they add that is missing here becomes a legitimate event rejected with "ip_not_allowed". Exact addresses only, CIDR ranges are not supported. Only read when [Enable IP check] is on.

The field comes pre-filled with the list Stripe published when this plugin version was released. That is a snapshot, not a live feed: confirm the current list at https://stripe.com/files/ips/ips_webhooks.json, because an address Stripe adds that is missing here turns a legitimate event into a rejection.

The IP address the request came from. Use Request Data's header cf-connecting-ip, not x-forwarded-for. The difference matters: x-forwarded-for is written by whoever makes the request and can be forged, so an attacker can simply claim to be a Stripe address, while cf-connecting-ip is written by Cloudflare, which sits in front of Bubble, and is overwritten on every request. If a chained value is passed anyway, only the last address in the chain is checked, which is the one added by the infrastructure and not by the caller. Only read when [Enable IP check] is on.

Use Request Data's header cf-connecting-ip, not x-forwarded-for. The second one is written by whoever makes the request, so an attacker can simply claim to be a Stripe address and pass this check; the first is written by Cloudflare, which sits in front of Bubble, and is overwritten on every request. If a chained value arrives anyway, only the last address in the chain is checked, which is the one the infrastructure added and not the one the caller invented. Stripe asks for this check and signature verification, not one or the other: they cover different attacks.

Yes when the signature matches, the event is within the tolerance window, and the environment check passed. No otherwise. Treat it as the gate: terminate the workflow when it is no, and do not process the event any further.

The cause of the rejection, as a stable text code. Empty when [is valid] is yes. This is the value to write into logs and audit records; for branching the workflow, use the yes/no below instead, because a typo in a text comparison never matches and never warns.

• missing_inputsone or more required fields are empty. The action cannot proceed without a secret, a signature and a raw body.
• malformed_headerthe Stripe-Signature header is missing or has an unexpected format. The timestamp or the signature value could not be extracted.
• signature_mismatchthe computed signature does not match any signature received. The request did not come from Stripe, or the payload was modified in transit.
• timestamp_expiredthe event is older than the configured tolerance. The request may be a replay attack.
• livemode_check_misconfiguredthe livemode check is on but Accept events from the live version has no value, so there was nothing to compare the event against. The action refuses instead of guessing one of the two answers, because guessing would silently reject every event from the other environment.
• livemode_mismatchthe event is authentic, but it comes from the environment you chose to refuse in Accept events from the live version.
• ip_check_misconfiguredthe IP check is on but the allowlist or the request IP is empty, so there was nothing to check against. The action refuses instead of letting the event through, because a check you turned on and left unconfigured should fail loudly rather than quietly protect nothing.
• ip_not_allowedthe signature, the age and the environment all checked out, but the request came from an address that is not in your allowlist. The most common cause is not an attack: it is Stripe having added an address that your list does not have yet.

Yes when the secret, the signature or the raw body arrived empty. Nothing was verified: this is a configuration problem in your own workflow, not a suspicious request, and it deserves an alert to the developer rather than a silent log line.

Yes when the Stripe-Signature header is missing or has an unexpected format, so the timestamp or the signature could not be extracted. Usually means the wrong header was mapped into the field.

Yes when no signature in the header matches the one computed from your secret and the body. Either the request did not come from Stripe, or the body was altered on the way, or the secret belongs to another endpoint.

Yes when the signature is authentic but the event is older than the tolerance window. The request may be a replayed copy of a legitimate event, or your server clock may be out of sync.

True when the livemode check is on but Accept events from the live version is empty. Like the IP one, this is not about the event: it means your own setup is incomplete, so treat it as an alert rather than something to log and move on from.

True when the event is authentic but comes from the environment you chose to refuse in Accept events from the live version. The environment is read from inside the signed payload, so it cannot be forged.

True when the IP check is on but IP allowlist or Request IP is empty, so there was nothing to check against. This one is not about the event: it means your own setup is incomplete and the check is protecting nothing, so treat it as an alert rather than something to log and move on from.

True when the event is authentic but came from an address that is not in IP allowlist. It is the only cause that can be true while the signature itself is valid, so it means the event is genuine and was refused on origin alone.

The environment the event was created in, live or test. It is read from inside the signed payload, so it cannot be forged. Useful in the audit line, where live or test reads better than a yes/no.

• livethe event was created in live mode.
• testthe event was created in test mode.

The Stripe event id, such as evt_1UMBru... This is the key to store so a redelivered event is never processed twice: Stripe retries delivery, and the same event arrives with the same id.

The event type, such as checkout.session.completed. Use it to route the workflow without parsing the body a second time.

When Stripe created the event, as a Unix timestamp in seconds. It is the envelope's own timestamp, which can be a few seconds later than the creation time of the object inside it.

How many seconds passed between the signature timestamp and the moment the action ran. The same number the tolerance check uses, exposed so your audit trail can record how late an accepted event was.

The id of the object carried by the event, such as cs_test_... Look it up in the Stripe API to confirm the current state at the source, instead of trusting what the payload says, because events can arrive out of order.

The type of the object carried by the event, such as checkout.session. It tells you which Stripe endpoint to call with [inner object id].

Every returned value above, as one text block, one per line, in the form name: value. Booleans come as yes and no, and empty values keep their line so two executions stay comparable. Built for storing an audit line or pasting into a support ticket without rebuilding the list by hand in a workflow. It carries only returned values: the signing secret, the signature and the raw body are never in it, so this text is safe to store.