Webhook Configuration

Get notified the instant a payment succeeds. PayRequest can send a signed HTTP request to your own server every time a Transaction is marked paid — regardless of which payment method or provider was used (Mollie, Stripe, PayPal, bank transfer, crypto, etc).

Currently one event is supported: payment.succeeded. You can configure a single webhook URL per account.

Setting Up Your Webhook

Open API & Webhook settings

Go to Settings → API Tokens in your dashboard.

Enter your webhook URL

Enter the HTTPS endpoint on your server that should receive payment notifications.

Save — a signing secret is generated

The first time you save a webhook URL, PayRequest generates a webhook secret used to sign every request. You’ll need this to verify incoming requests.

Verify signatures on your server

Use the secret to validate the X-PayRequest-Signature header on every request you receive (see below).

You can regenerate your webhook secret at any time from the same settings page if you suspect it’s been exposed. Doing so immediately invalidates the old secret.

Payload

When a transaction is marked paid, PayRequest sends a POST request with this JSON body:

{
  "event": "payment.succeeded",
  "timestamp": "2026-07-13T10:15:00+00:00",
  "data": {
    "id": 48213,
    "amount": 49.00,
    "currency": "EUR",
    "description": "Invoice #1042",
    "payment_link_id": 1809,
    "payment_method": "ideal",
    "reference": "tr_abc123",
    "paid_at": "2026-07-13T10:14:58+00:00",
    "customer": {
      "id": 512,
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

Field	Description
`event`	Always `payment.succeeded` currently
`timestamp`	When the webhook was dispatched (ISO 8601)
`data.id`	PayRequest transaction ID
`data.amount`	Amount as a decimal (never divided/multiplied — matches what the customer paid)
`data.currency`	ISO currency code, defaults to `EUR`
`data.payment_link_id`	Smart Link ID, if the payment came from one
`data.payment_method`	Payment method used (`ideal`, `creditcard`, `crypto_usdc`, etc)
`data.reference`	Provider-specific transaction reference
`data.customer`	`null` if no customer is attached to the transaction

Verifying the Signature

Every request includes an X-PayRequest-Signature header in the form sha256={hmac}, where {hmac} is an HMAC-SHA256 of the raw JSON body, signed with your webhook secret.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYREQUEST_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $yourWebhookSecret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Always compare signatures with a constant-time function (like PHP’s hash_equals) to avoid timing attacks. Never compare with == or ===.

Delivery Behavior

Webhooks are dispatched asynchronously via a queued job as soon as a transaction is marked paid
Requests time out after 10 seconds
Delivery is best-effort — PayRequest does not currently guarantee automatic retries if your endpoint is unreachable or returns an error, so make sure your endpoint responds quickly and reliably
Only one webhook URL is supported per account; every payment.succeeded event goes to the same endpoint

Since delivery isn’t guaranteed to retry, treat webhooks as a fast notification layer rather than your only source of truth. You can always confirm a payment by checking the transaction or invoice status in the PayRequest dashboard or via the API.

Testing Your Endpoint

There’s no built-in webhook test-send tool yet — the simplest way to test is to trigger a real (or testmode) payment and confirm your endpoint receives and correctly verifies it. Tools like webhook.site or ngrok are useful for inspecting payloads during local development.

FAQ

Can I have multiple webhook URLs?

Not yet — one webhook URL per account. If you need to notify multiple systems, have your endpoint fan the event out internally.

What happens if my endpoint is down?

The request will fail and the failure is logged on PayRequest’s side, but it is not automatically retried. Make sure your endpoint has good uptime, and reconcile periodically against the dashboard or API as a safety net.

Does this fire for crypto and manual/bank transfer payments too?

Yes. The webhook fires whenever a Transaction record is marked paid, regardless of payment method — including crypto (USDC), bank transfers, and manually recorded payments.

Next Steps

API Reference

Query transactions and invoices directly instead of (or alongside) webhooks

Webhook Development

Advanced patterns for building against PayRequest webhooks

Smart Links

See how payment_link_id maps back to a Smart Link

🚀 Getting Started

🔌 API Reference

🤖 MCP Integration

💳 Payment Processing

📦 Products & Pricing

🧑‍💻 Freelancers & Creators

🔄 Subscriptions

📋 Debt Collection

📄 Invoices

🛍️ Shop & Checkout

👥 Customer Management

🏷️ Organization & Automation

📊 Analytics & Reporting

🏢 Business Settings

🔗 Integrations

🔒 Security & Compliance

🔧 Advanced Features

📝 Updates & Changes

🆘 Troubleshooting

Webhook Configuration

Webhook Configuration

Setting Up Your Webhook

Payload

Verifying the Signature

Delivery Behavior

Testing Your Endpoint

FAQ

Next Steps

API Reference

Webhook Development

Smart Links

​Webhook Configuration

​Setting Up Your Webhook

​Payload

​Verifying the Signature

​Delivery Behavior

​Testing Your Endpoint

​FAQ

​Next Steps

API Reference

Webhook Development

Smart Links

Webhook Configuration

Setting Up Your Webhook

Payload

Verifying the Signature

Delivery Behavior

Testing Your Endpoint

FAQ

Next Steps