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

# Receiver examples

> Optional Node.js and Python examples for accepting signed webhook events.

These examples are optional starting points for your server. **Prava webhooks work with any backend language or framework.** The runtime versions below are requirements for these example programs, not for the webhook API.

Using only their language's standard library, both examples:

* verify the signature on the raw request body
* check the application and environment
* echo verification challenges
* save events in SQLite before returning a successful response, with a unique event-ID constraint that prevents duplicate inbox entries

## Configure an example

Download the example for your language from the source links below. Then create a private configuration file **outside your repository**:

```json theme={null}
{
  "account_id": "ma_YOUR_APP",
  "environment": "sandbox",
  "secrets": ["whsec_YOUR_SECRET"]
}
```

| Field | Value |
| - | - |
| `account_id` | Your application ID |
| `environment` | The endpoint's environment, for example `sandbox` |
| `secrets` | The endpoint's signing secret (`whsec_...`) |

Set the file's permissions to `0600` so only its owner can read or modify it, and point the example at it:

```bash theme={null}
chmod 600 /absolute/path/webhook-config.json
export WEBHOOK_CONFIG_PATH=/absolute/path/webhook-config.json
export WEBHOOK_INBOX_PATH=/absolute/path/webhook-inbox.sqlite
```

| Variable | Purpose |
| - | - |
| `WEBHOOK_CONFIG_PATH` | The private configuration file above |
| `WEBHOOK_INBOX_PATH` | A private, durable SQLite file for the inbox |
| `PORT` | Optional. A different local port (default `8787`). |

The paths in these commands are placeholders; replace them with your local paths.

> [!WARNING]
>
> The `whsec_...` value is the webhook endpoint signing secret. Don't substitute an application API key, commit this file or log its contents.

## Run your preferred example

> [tab] Node.js
>
> The [Node.js receiver source](https://github.com/Prava-Payments/prava-docs/blob/main/examples/webhooks/receiver.mjs) is supported on **Node.js 24 or later**. It uses Node's built-in SQLite module, so this complete example isn't intended for older runtimes. This requirement doesn't apply to the JavaScript verification function or to your own receiver.
>
> Run the downloaded file:
>
> ```bash theme={null}
> node receiver.mjs
> ```

> [tab] Python
>
> The [Python receiver source](https://github.com/Prava-Payments/prava-docs/blob/main/examples/webhooks/receiver.py) uses **Python 3** and its standard library, including SQLite. No third-party packages are required.
>
> Run the downloaded file:
>
> ```bash theme={null}
> python3 receiver.py
> ```

Both examples listen at `http://127.0.0.1:8787/webhooks` by default. Expose them through a reverse proxy for your public HTTPS endpoint, or a temporary HTTPS tunnel for sandbox testing. Register the public URL in the dashboard; the local HTTP address isn't a valid delivery destination.

## Process stored events

A separate consumer reads unprocessed `webhook_inbox` records. In one application transaction, it should:

1. Deduplicate side effects by event ID.
2. Ignore `test: true` events for business effects.
3. Apply only a newer resource version.
4. Set `processed_at`.

For external side effects, use that service's idempotency mechanism.

A successful webhook response confirms receipt, not completion of your business processing. SQLite here demonstrates durable acceptance on a single host. For a receiver deployed across multiple hosts, use a shared production database or durable queue with equivalent deduplication.

Leave `WEBHOOK_E2E_CONTROL_KEY` and `WEBHOOK_E2E_ACCOUNT_ID` unset for an ordinary receiver. Those options are only for [automated sandbox tests](https://docs.prava.space/webhooks/testing.md#advanced-automated-sandbox-receiver).

[Verify signatures](https://docs.prava.space/webhooks/security.md) · [Test your integration](https://docs.prava.space/webhooks/testing.md) · [Delivery and recovery](https://docs.prava.space/webhooks/delivery.md)


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