Stripe Integration
Create issues from your customer payment failures, disputes, refunds and subscription changes.
This connection receives events from your Stripe account. Velocity’s own subscription billing is managed separately under Billing.
Setup
- As a workspace admin or owner, open Settings → Integrations → Stripe and select Set up Stripe.
- Choose a default team, or choose a team for each event. Select the events you want to import and save your settings.
- Copy the Stripe webhook URL. In Stripe Workbench, create an event destination for your account. Use a webhook endpoint with snapshot events, paste this URL and select the matching event types below.
- Reveal the destination’s signing secret in Stripe and paste it into Velocity’s signing-secret field. Store it once; Velocity never displays the saved value.
- Send a supported test event from a Stripe sandbox. Refresh Recent Stripe activity to see its result and linked issue. Last signed event processed confirms an authenticated delivery was handled, including an intentionally filtered event.
Sandbox and live destinations have different signing secrets. Use the secret for the destination whose URL you copied. For rotation, store the replacement secret and choose how long the old secret remains accepted; end the overlap early if needed.
See Stripe’s webhook setup guide for Workbench and sandbox testing.
Supported events
| Snapshot event | Behavior | Default priority |
|---|---|---|
payment_intent.payment_failed | Create a payment-failure issue | High |
charge.dispute.created | Create one issue for the dispute | Urgent |
charge.dispute.closed | Complete the linked dispute issue when auto-close is enabled | Uses existing issue |
customer.subscription.deleted | Create a cancellation issue | Medium |
customer.subscription.updated | Create an issue for a lower comparable recurring rate | Medium |
invoice.payment_failed | Create an invoice-failure issue | High |
charge.refunded | Create a refund issue with the cumulative amount refunded for that charge | Medium |
charge.failed | Legacy charge-failure support | High |
The correct dispute event prefix is charge.dispute. Unsupported or disabled event types are recorded as ignored and do not create issues. If both payment-intent and charge failure events are enabled, Stripe can deliver distinct events for the same failed payment; each selected event can create its own issue.
Issue routing
Set a default team, status, priority, assignee, labels and title template. Each creation event can override those defaults. Statuses must belong to the chosen team; assignees and labels must belong to the workspace. Changing the default team clears inherited status and label overrides that could be invalid for the new team.
With automatic priority, disputes are Urgent, failures are High, and cancellation, downgrade and refund issues are Medium. A blank status uses the team’s default, and a blank assignee leaves the issue unassigned. Custom labels can be an empty list to override inherited labels. Issues are attributed to a workspace owner and carry the Stripe source.
Title templates
Use these placeholders:
{{customer}}, {{customer_name}}, {{customer_email}}, {{amount}}, {{currency}}, {{reason}}, {{object_id}}, {{event_type}}For example:
Payment {{object_id}} failed — {{customer}} — {{currency}} {{amount}}Amounts are formatted in the payment currency’s Stripe denomination. Customer details and failure reasons are included when the snapshot supplies them. When a customer is only an ID, the issue uses that ID; Velocity does not fetch extra customer data. Descriptions also include the event ID, object ID and Stripe Dashboard link.
Filters and subscription downgrades
Minimum payment amount uses major units in the incoming currency: 10 means USD 10 or JPY 10. It applies to known payment, invoice, dispute and cumulative refunded amounts. It does not apply to subscriptions or dispute closure.
Customer email domains is a comma-separated list of exact domains. An event with no email cannot match a domain filter. Leave the list empty to allow all customers. Dispute-close events follow the existing issue regardless of these filters.
A subscription update creates an issue only when the previous snapshot supports comparing fixed recurring prices and quantities in the same currency. Monthly and yearly prices are normalized to a yearly rate; daily and weekly prices to a weekly rate. Upgrades, unrelated changes, metered prices, mixed currencies and incomplete snapshots are ignored. Coupon, tax and usage changes are not interpreted as plan downgrades.
Retries and dispute closure
Successful Stripe event IDs are processed once per integration. Concurrent deliveries return a retryable response until the current attempt finishes. Failed issue creation or label attachment returns an error so Stripe can resend; a retry repairs a partially created issue instead of creating another one.
Closing a dispute uses the existing issue’s team and first completed status. Already completed or cancelled issues keep their status. If the close arrives first, Velocity records it and completes the issue when its create event arrives. Disabling the close event or auto-close prevents this behavior. A missing completed status causes a retryable failure; add one and resend the event.
Activity shows created, resolved, closed, ignored, processing or failed deliveries. For a failed delivery, check routing, signing-secret configuration and the team’s statuses, then resend from Stripe. HTTP 503 means another attempt is still processing; HTTP 500 means the delivery could not finish.
Security and connection scope
Each delivery requires a valid Stripe HMAC signature on its exact raw body, with a five-minute timestamp tolerance. Signing secrets are encrypted and write-only, and receipt claims are restricted to the server. Routing and issue access are checked within the workspace.
This setup uses a webhook signing secret and does not require a Stripe API key. Stripe Connect OAuth and customer enrichment are not part of this connection.