neo-pays

Webhooks

Generated page, from the OpenAPI specification the gateway serves (GET /v1/openapi.json). Do not edit it by hand: it is rewritten on every build.

Method Path Description
GET /v1/webhooks List your notification endpoints
POST /v1/webhooks Register an endpoint
POST /v1/webhooks/test Trigger a test delivery
GET /v1/webhooks/{id} Retrieve an endpoint
PATCH /v1/webhooks/{id} Update an endpoint
DELETE /v1/webhooks/{id} Delete an endpoint
GET /v1/webhooks/{id}/secret Read the signing secret again

GET /v1/webhooks

List your notification endpoints

Your endpoints, with their delivery counters. consecutive_failures is the field to look at when notifications stop: twenty consecutive failures suspend an endpoint for an hour, and a single success restores it.

ⓘ Endpoints are NOT separated between test and live: a test key and a live key see the same ones.

Responses

  • 200 — OK
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

POST /v1/webhooks

Register an endpoint

⚠️ THIS CALL GUARANTEES, IT DOES NOT ALWAYS CREATE. A URL already registered comes back as 200 rather than being duplicated, so a provisioning script run twice leaves ONE endpoint and not two receiving every event in duplicate. The secret is returned in both cases, because the legitimate reason to call again is having lost it.

Ten endpoints per account at most. An empty subscribed_events means all events; otherwise, from: payment.initiated, payment.pending, payment.success, payment.failed, payout.success, payout.failed, payout.cancelled, payout.refunded, refund.success, refund.failed, and the subscription.* family.

Responses

  • 200 — The endpoint already existed for this URL
  • 201 — Endpoint created
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 422 — Non-HTTPS URL, event outside the catalogue, or ten endpoints already registered
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

POST /v1/webhooks/test

Trigger a test delivery

Sends a payment.test event to ALL your active endpoints and returns the result of each delivery. Nothing is persisted and no money is at stake — this is how you check your signature verification before the first real payment.

ⓘ Scope can_read_transactions, not can_manage_webhooks: the call changes no configuration.

Responses

  • 200 — The result for each endpoint
  • 400 — No active endpoint to deliver to
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

GET /v1/webhooks/{id}

Retrieve an endpoint

The same object as in the list.

Parameters

Name In Required Description
id path yes The endpoint's number, as returned by GET /v1/webhooks.

Responses

  • 200 — OK
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 404 — No endpoint with that number on this account
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

PATCH /v1/webhooks/{id}

Update an endpoint

A PARTIAL update: only the fields sent change. Omitting is_active does not deactivate the endpoint, and omitting description does not clear it — which is not a subtlety, since the opposite would mean a call renaming an endpoint silently stopped its own deliveries.

is_active: false suspends deliveries without losing the endpoint or its secret.

Parameters

Name In Required Description
id path yes The endpoint's number, as returned by GET /v1/webhooks.

Responses

  • 200 — OK
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 404 — No endpoint with that number on this account
  • 422 — Non-HTTPS URL or event outside the catalogue
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

DELETE /v1/webhooks/{id}

Delete an endpoint

Permanent. To stop deliveries without losing the endpoint and its secret, prefer PATCH with is_active: false.

Parameters

Name In Required Description
id path yes The endpoint's number, as returned by GET /v1/webhooks.

Responses

  • 204 — Deleted
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 404 — No endpoint with that number on this account
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After

GET /v1/webhooks/{id}/secret

Read the signing secret again

ⓘ YES, THIS ONE CAN BE READ AGAIN, unlike an API key's secret. The difference is not an inconsistency: the platform must hold the webhook secret in order to SIGN, so it is stored recoverably. An API key is stored only as a fingerprint, and therefore cannot be read back.

Parameters

Name In Required Description
id path yes The endpoint's number, as returned by GET /v1/webhooks.

Responses

  • 200 — OK
  • 401 — API key missing or rejected
  • 403 — The key does not carry the can_manage_webhooks scope
  • 404 — No endpoint with that number on this account
  • 429 — The key's request budget is exhausted (300/min) — honour Retry-After