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

# Webhooks & API overview

> How Pocketsflow webhooks and the HTTP API work together to keep your systems in sync.

Pocketsflow gives you two complementary programmatic surfaces:

* **Webhooks** push events to you the moment they happen — a sale completes, a
  subscription's initial payment or a renewal succeeds, a payment fails, a
  refund is issued.
* The **HTTP API** lets you read and write on demand — list orders and payments,
  fetch subscribers, create products and checkout sessions, register webhooks,
  and more.

Both are live today. A typical integration uses them together: react to a
webhook, then call the API to fetch extra detail or take a follow-up action.

<Card title="Open the interactive API reference" icon="server" href="https://api.pocketsflow.com/docs" horizontal>
  Browse every endpoint and try calls live at **api.pocketsflow\.com/docs**
  (OpenAPI JSON at `/docs.json`).
</Card>

## What you can do with webhooks

Use events to keep external systems in step with Pocketsflow:

* **Fulfil purchases** and grant access the instant `order.completed` fires.
* **Manage memberships** — provision on `customer.subscription.created` (it fires
  exactly once, on activation), keep access on each `invoice.payment_succeeded`
  renewal, and revoke on `customer.subscription.deleted`.
* **React to changes** — `customer.subscription.updated` fires on every change
  *after* activation (past due, recovery, cancel-scheduled, pause, resume).
* **Run dunning** — email or pause access on `invoice.payment_failed`, and warn
  ahead of a renewal with `invoice.upcoming` (3 days before the card is hit).
* **Handle pauses** — `customer.subscription.pause` stops billing but the buyer
  **keeps access**; `customer.subscription.resumed` when billing restarts.
* **Sync your CRM** — capture new buyers on `customer.created`.
* **Trigger refunds/returns workflows** on `order.refunded`.

See [Webhook events](/api-webhooks/events) for the full catalog and payloads.

## How delivery works

<Steps>
  <Step title="Register an endpoint">
    Create a webhook in the dashboard or via
    [`POST /webhooks`](/api-reference/introduction#webhooks) with an HTTPS `url`
    and the `events` you want. You get back a signing `secret`.
  </Step>

  <Step title="Pocketsflow POSTs the event">
    When a subscribed event occurs, Pocketsflow sends a JSON `POST` to your URL
    with `X-Pocketsflow-Event`, `X-Pocketsflow-Signature`, and
    `X-Pocketsflow-Timestamp` headers.
  </Step>

  <Step title="You verify and process">
    Verify the HMAC-SHA256 signature against the raw body, then process the
    event idempotently.
  </Step>

  <Step title="You acknowledge">
    Return a `2xx` within 5 seconds. Every attempt is recorded in your webhook
    delivery log.
  </Step>
</Steps>

<Note>
  Deliveries are a **single attempt** with a **5-second timeout** — there is no
  automatic retry of the outbound call. Acknowledge fast, process
  asynchronously, and reconcile via the API (for example
  [`GET /payments`](/api-reference/introduction#payments)) so a missed delivery
  never leaves you out of sync. You can also re-send a sample event any time
  with [`POST /webhooks/{id}/test`](/api-reference/introduction#webhooks).
</Note>

## Test vs live

Webhook endpoints are scoped to the mode your account is in when you create
them. A test-mode endpoint only receives events from `pk_test_…` sales; a
live-mode endpoint only receives live events. Keep separate endpoints (and
secrets) per mode.

## Where to go next

* [API reference](/api-reference/introduction) — base URL, API keys, pagination, errors, and the complete endpoint catalog.
* [Authentication & security](/api-webhooks/authentication-and-security) — verifying webhook signatures and securing your endpoint.
* [Webhook events](/api-webhooks/events) — every event, when it fires, and its payload.
* [Consuming webhooks](/api-webhooks/consuming-webhooks) — delivery, idempotency, and reconciliation best practices.
* [Webhook examples](/api-webhooks/examples) — ready-to-adapt handler code.
* [Integrations](/integrations/overview) — connect Pocketsflow to platforms like WooCommerce.