> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Get notified in real time when payments, expenses and payouts change in Pazy

Webhooks let Pazy tell your system when something happens, so you don't have to poll the API. When an event occurs, Pazy sends an HTTPS `POST` with a signed JSON body to the endpoint you registered.

Use webhooks to:

* Confirm that an invoice payment settled, failed or was reversed, including payments made in large async batches.
* React to card and UPI transactions as they succeed, fail or get declined.
* Collect expense receipts as soon as they're uploaded.
* Follow expenses through approval and accounting sync.
* Track payout transactions to the bank.

## How it works

<Steps>
  <Step title="Something happens in Pazy">
    For example, an invoice payment settles. Pazy records an event with a unique `id`.
  </Step>

  <Step title="Pazy delivers it">
    Pazy sends a `POST` to every endpoint of your organization that is subscribed to that event type. The body is signed with your endpoint's secret.
  </Step>

  <Step title="You verify and acknowledge">
    Your handler checks the [signature](/webhooks/verify-signatures), saves the event, and replies with a `2xx` status quickly.
  </Step>

  <Step title="Pazy retries if needed">
    Any other response, or no response in time, triggers [retries](/webhooks/delivery-and-retries) with exponential backoff, up to 5 attempts.
  </Step>
</Steps>

## What you need to know first

<CardGroup cols={2}>
  <Card title="At-least-once delivery" icon="rotate">
    The same event can arrive more than once. Deduplicate on the event `id`.
  </Card>

  <Card title="No ordering guarantee" icon="shuffle">
    A retried event can arrive after a newer one. Use timestamps and status fields, not arrival order.
  </Card>

  <Card title="Signed requests" icon="shield-check">
    Always verify `X-Pazy-Webhook-Signature` before trusting a payload.
  </Card>

  <Card title="Sandbox supported" icon="flask">
    Webhooks work in the sandbox too, with the same payloads and signing.
  </Card>
</CardGroup>

## Get started

<CardGroup cols={2}>
  <Card title="Set up an endpoint" icon="plug" href="/webhooks/setup">
    Request an endpoint, choose events, and meet the URL requirements.
  </Card>

  <Card title="Verify signatures" icon="lock" href="/webhooks/verify-signatures">
    Working code for Node.js, Python and Go.
  </Card>

  <Card title="Event reference" icon="list" href="/webhooks/events/overview">
    Every event type with its payload fields and an example.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/webhooks/troubleshooting">
    Fix signature failures, missing events and duplicate deliveries.
  </Card>
</CardGroup>

## Webhooks and the API

Webhooks tell you that something changed. They are not a replacement for the API. When you need the full record, use the `id` in the event to fetch it, for example with [Expense Details](/apis/expense-details). Treat the API as the source of truth if you ever suspect you missed an event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.