Skip to main content
Webhooks push events to your server as they happen — payments, paywall and service changes — so you don’t have to poll Transactions or Events. Each delivery is a signed HTTP POST to an endpoint you control.
Webhooks are configured from the dashboard only. There is no API to create or manage endpoints.

​
Add an endpoint

In the dashboard, open Webhooks and click Add endpoint:
FieldDescription
Endpoint URLThe HTTPS URL Proceeds sends events to — for example https://api.example.com/webhooks/proceeds.
DescriptionOptional label to identify the endpoint.
Events to sendThe event types this endpoint receives. Use Select all or pick individually.
You can configure up to 20 endpoints. Each endpoint can subscribe to a different set of events.

​
Events

Choose which events each endpoint receives:
GroupEventFires when
Paymentspayment.requestedA 402 challenge was issued for a request.
payment.pendingA payment attempt exists but isn’t yet validated and proxied.
payment.succeededA payment was validated and the request was proxied successfully.
payment.failedA payment or fulfillment failed.
Paywallspaywall.createdA paywall was created.
paywall.updatedA paywall was updated.
paywall.deletedA paywall was deleted.
Servicesservice.createdA service was created.
The payment events mirror transaction state and the request lifecycle — webhooks are the push-based equivalent.

​
Verify each delivery

Every request includes an X-Webhook-Signature header. Each endpoint has its own signing secret (prefixed whsec_), shown in the endpoint list. Before trusting a payload:
  1. Read the X-Webhook-Signature header from the incoming request.
  2. Compute the expected signature from the raw request body using your endpoint’s whsec_ secret.
  3. Reject the request if the signatures don’t match.
Treat the whsec_ secret like an API key — store it server-side and never expose it. Always verify the signature before acting on a webhook; never trust an unverified payload.

​
Delivery and retries

Proceeds expects your endpoint to respond with a 2xx status. If it doesn’t, the delivery is retried — up to 3 attempts per event. Open an endpoint’s Recent deliveries to inspect history:
ColumnMeaning
EventThe event type delivered.
StatusSucceeded or failed.
CodeThe HTTP status your endpoint returned.
AttemptsDelivery attempts used, out of 3.
TimeWhen the delivery was sent.
ResendManually replay the delivery.

​
Manage endpoints

The Webhooks list shows each endpoint’s Status (active or paused), subscribed Events, Last delivery, and signing Secret. From there you can pause, edit, or delete an endpoint.

​
Best practices

  • Respond fast. Return 2xx immediately and process the event asynchronously so deliveries don’t time out.
  • Verify the signature. Always check X-Webhook-Signature before acting on a payload.
  • Be idempotent. A retried or resent delivery can arrive more than once — de-duplicate on the event so repeats are safe.
  • Subscribe narrowly. Only enable the events each endpoint actually needs.

Transactions

The payment state that payment.* events mirror.

Events

The request lifecycle you can also inspect in the dashboard.