Payment webhooks

Subscribe to payment lifecycle events so you can reconcile server-side instead of polling. A payment request emits exactly one terminal event.

Event	Fires when
payment.succeeded	The recipient paid. The request’s status is now succeeded. For mode: subscription requests this is the first invoice being paid and the subscription activating — renewals emit your own Stripe webhooks, not Linq events.
payment.canceled	You cancelled the request before it was paid.
payment.expired	The request reached its expires_at without being paid.

Each payload carries the full payment request — id, mode, amount, currency, the metadata you set on creation, and for subscriptions the recurrence (price_id, interval, interval_count, quantity, plus trial_end on free trials, where payment.succeeded means the payment method was collected and $0 moved) — so you can match the event back to your own order or chat record without a second API call. The stripe object carries the ids of the objects on your connected account (payment_intent_id, plus customer_id whenever the request is attached to a Customer — always for subscriptions, and in payment mode when you created the request with a customer_id — and subscription_id for subscriptions) — your join keys for managing the ongoing lifecycle in Stripe. A rail field (stripe or natural) tells you which rail the request settled on; on the Natural rail the payload carries a natural object with its join keys (payment_request_id, a prq_..., and transaction_id, a txn_...) in place of the stripe object. The canonical payload shapes are in the Webhooks API reference.

:::note[Natural rail: wallet activity beyond your requests] These payment.* webhooks fire only for payment requests you create through Linq. On the Natural rail, other wallet activity — incoming payments made outside a Linq request, transfers, deposits, and payouts — happens on your Natural account and is not bridged here. To see or get notified of it, use your Natural dashboard or register your own webhooks in Natural against your account. :::

Create a webhook subscription targeting your endpoint and filtered to the payment events you care about. The full subscription lifecycle — create, list, update, delete, versioning, and signature verification — is covered in the Webhooks guide. Payment events use the same delivery, retry, and Standard Webhooks signing scheme as every other Linq event, so if you already verify webhooks, nothing new is required.

Treat the webhook as the source of truth for a request reaching a terminal state:

• On payment.succeeded, mark your order paid using the metadata you attached.
• On payment.expired or payment.canceled, release or re-issue as appropriate.

If you miss an event (endpoint downtime, etc.), you can always fetch the current state with Retrieve a payment request — status and paid_at reflect the same outcome the webhook reported.

• Payments overview
• Webhooks — subscriptions and signature verification.