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

Webhook event object 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.
2

Register it in the dashboard

In the dashboard, 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.
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 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.
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.
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.

What a delivery looks like

The body is an envelope:
string
The event id. It is the same on every retry of this event. Use it to process the event once.
string
One of the seven event types.
string
Your Payve account id.
object
The transaction the event is about.
string
When the event was created, ISO 8601 in UTC.

Your side of the contract

Verify the signature

Reject anything that is not signed by Payve, or is too old.

Expect retries

Deliveries are at-least-once. Failed ones are retried for days.

Process each event once

Record the event id, answer fast, work afterwards.

See every payload

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.