---
title: Payment webhooks | API Docs
description: Reconcile payments server-side with the payment.succeeded, payment.canceled, and payment.expired events.
---

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

## Events

| Event               | Fires when                                                     |
| ------------------- | -------------------------------------------------------------- |
| `payment.succeeded` | The recipient paid. The request’s `status` is now `succeeded`. |
| `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 payment request `id`, `amount`, `currency`, and the `metadata` you set on creation — so you can match the event back to your own order or chat record without a second API call. The canonical payload shapes are in the [Webhooks API reference](/api/resources/webhooks/index.md).

## Subscribing

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](/guides/webhooks/index.md). Payment events use the same delivery, retry, and [Standard Webhooks](https://www.standardwebhooks.com/) signing scheme as every other Linq event, so if you already verify webhooks, nothing new is required.

## Reconciling

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](/api/resources/payment_requests/methods/retrieve/index.md) — `status` and `paid_at` reflect the same outcome the webhook reported.

## Related

- [Agent Pay overview](/guides/payments/index.md)
- [Webhooks](/guides/webhooks/index.md) — subscriptions and signature verification.