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

# Webhooks overview

> Payve posts a signed event to your server when a payout, pay-in or conversion finishes.

A webhook is an HTTPS `POST` from Payve to a URL you own. It tells you a transaction has finished, so you do not have to poll.

## The seven events

| Event | Sent when |
| - | - |
| `payout.successful` | A payout arrived. |
| `payout.failed` | A payout did not arrive. The money is back in your wallet. |
| `payin.successful` | A pay-in was received. |
| `payin.failed` | A pay-in failed. |
| `payin.expired` | A pay-in was not paid in time. |
| `conversion.successful` | A conversion completed. |
| `conversion.failed` | A conversion did not complete. |

[Webhook event object](/webhooks/event-samples.md) shows a full payload for each.

## Add an endpoint

**1. Build the receiver**

Expose an HTTPS route on your server that accepts a JSON `POST`. Start from the code in [Verify signatures](/webhooks/verify-signatures.md).

**2. Register it in the dashboard**

In the [dashboard](https://app.payvehq.com), choose the environment, open **Settings → Webhooks** and add your URL. Choose **All events**.

**3. Save the signing secret**

The dashboard shows a secret that starts with `whsec_`. Store it where your server can read it.

> [!WARNING]
>
> The signing secret is shown once. Payve keeps it encrypted and never returns it again, not in the dashboard and not through the API. If you lose it, add a new endpoint to get a new secret.

**4. Test it**

In the sandbox, send a payout to a [test account](/testing/sandbox.md#payouts) and watch the delivery under **Settings → Webhooks**.

### Rules for the URL

* It must use `https`. An `http` URL is never called.
* It must resolve to a public address. Payve does not deliver to `localhost`, private networks or link-local addresses.
* It must answer directly. Payve does not follow redirects, so a `301` or `302` counts as a failed delivery.
* It must answer within 30 seconds. Aim for under five.

> [!TIP]
>
> To receive sandbox webhooks on your laptop, put a public HTTPS tunnel in front of your local
> server and register the tunnel's URL.

### Choosing events

An endpoint with **All events** receives everything. If you pick specific events, the endpoint receives only events whose `type` matches one of them exactly.

> [!WARNING]
>
> Subscribe to **All events** and filter by `type` in your code. An endpoint subscribed to a name
> that is not one of the seven above receives nothing.

### Endpoints belong to an environment

A sandbox endpoint receives sandbox events only. A live endpoint receives live events only. Add one in each. See [Going live](/get-started/going-live.md).

## What a delivery looks like

```http
POST /webhooks/payve HTTP/1.1
Content-Type: application/json
X-Payve-Event: payout.successful
X-Payve-Timestamp: 1763460017
X-Payve-Signature: t=1763460017,v1=5c7e0d6a1b9f48e2c3a7d4f1e8b2a6c9d0e3f5a7b1c4d8e2f6a9b3c7d1e5f0a4
```

| Header | Value |
| - | - |
| `X-Payve-Event` | The event type, the same as `type` in the body. |
| `X-Payve-Timestamp` | When this delivery was signed, in Unix seconds. |
| `X-Payve-Signature` | `t=<timestamp>,v1=<signature>`. See [Verify signatures](/webhooks/verify-signatures.md). |
| `X-Payve-Signature-Previous` | Present only for 24 hours after a signing secret is rotated. Signed with the old secret. |

The body is an envelope:

```json
{
  "id": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
  "type": "payout.successful",
  "merchantId": "318",
  "data": { "...": "the transaction" },
  "createdAt": "2026-11-18T10:00:17.000Z"
}
```

**id** `string`

The event id. It is the same on every retry of this event. Use it to process the event once.

**type** `string`

One of the seven event types.

**merchantId** `string`

Your Payve account id.

**data** `object`

The transaction the event is about.

**createdAt** `string`

When the event was created, ISO 8601 in UTC.

## Your side of the contract

> [card] [Verify the signature](/webhooks/verify-signatures.md)
>
> Reject anything that is not signed by Payve, or is too old.

> [card] [Expect retries](/webhooks/delivery-and-retries.md)
>
> Deliveries are at-least-once. Failed ones are retried for days.

> [card] [Process each event once](/webhooks/handling-events.md)
>
> Record the event id, answer fast, work afterwards.

> [card] [See every payload](/webhooks/event-samples.md)
>
> One full sample for each event.

## Read deliveries through the API

An API key can read your endpoints and delivery history. It cannot create, change or delete endpoints.

| Request | Returns |
| - | - |
| `GET /v1/webhooks/endpoints` | Your endpoints, without secrets. |
| `GET /v1/webhooks/events` | Deliveries, newest first. Filter with `status`, page with `cursor`. |
| `GET /v1/webhooks/events/{id}` | One delivery: the exact body sent, and what your server answered. |
