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

# Webhooks on your machine

> Receive real webhook events locally and trigger sample events on demand

Polar delivers webhooks to public URLs, which your local server does not have.
The CLI bridges that gap: `polar webhook listen` streams your organization's webhook
events to a local URL, and `polar webhook trigger` sends realistic sample events
whenever you need one, without waiting for a real checkout or subscription.

## Receive webhooks locally

**1. Sign in and choose an organization**

```bash Terminal theme={null}
polar auth login --sandbox
```

Pick the organization you want to receive events for. See
[Authentication](https://polar.sh/docs/integrate/cli/authentication.md) for details.

**2. Start listening**

Point the CLI at the URL your webhook handler listens on:

```bash Terminal theme={null}
polar webhook listen http://localhost:3000/api/webhooks
```

```text theme={null}
  ● Connected  Acme
  Forwarding   http://localhost:3000/api/webhooks
  Secret       6t3c8ce2247c493a3ade20uea4484d64  use this to verify signatures locally

  Waiting for events... press Ctrl+C to stop
```

**3. Set the webhook secret**

Events are signed with the secret shown in the banner, exactly like
production deliveries. Configure your handler with it so signature
verification passes:

```bash .env theme={null}
POLAR_WEBHOOK_SECRET=6t3c8ce2247c493a3ade20uea4484d64
```

Every webhook event for the organization is now forwarded to your URL with the
same headers and body a public endpoint would receive, and each delivery is
logged with its status code and duration. The connection reconnects on its own
if it drops. Press `Ctrl+C` to stop.

> [!NOTE]
>
> Events follow the active organization's environment. Listen with a sandbox
> organization while developing, and switch with `polar auth org` when you need
> production events.

## Trigger sample events

With `polar webhook listen` running in one terminal, send a sample event from another:

```bash Terminal theme={null}
polar webhook trigger order.created
```

The CLI generates a realistic payload for the event, delivers it through your
`listen` session, and reports where it went. Nothing is created in your
organization. Run it without an event name to pick one from a list, or print
the catalog:

```bash Terminal theme={null}
polar webhook trigger --list
```

### Shape the payload

Override any field with `path=value`, repeating the flag as needed. Values are
sent as text unless you pass `null`, a JSON object, an array or a quoted string:

```bash Terminal theme={null}
polar webhook trigger order.created \
  --override data.customer.email=jane@example.com \
  --override data.net_amount=4900
```

Generated IDs and values are random on every run. Pass any integer as
`--seed` to make them deterministic, so the same seed always produces the same
payload, which is handy for scripted tests:

```bash Terminal theme={null}
polar webhook trigger subscription.active --seed 42
```

### Inspect without sending

Print the payload instead of delivering it:

```bash Terminal theme={null}
polar webhook trigger checkout.created --dry-run
```

## Next steps

* [Webhook events](https://polar.sh/docs/integrate/webhooks/events.md) documents every event and its
  payload.
* [Delivery](https://polar.sh/docs/integrate/webhooks/delivery.md) explains signatures, retries and
  timeouts for production endpoints.


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