Skip to main content
Webhooks let Orqex push events to your server as things happen, so you don’t have to poll. This page covers how delivery works across the platform; for the list of payment events and their payload, see payment webhooks.

​
Receiving events

There are two ways to receive events:

Per-payment

Set a webhook_url when you create a payment intent or checkout. That payment’s events are delivered there.

Project endpoints

Register webhook endpoints in the dashboard to receive events for the whole project.

​
Delivery

  • Orqex sends an HTTP POST with a JSON body to your URL.
  • Headers include X-Payment-Event (the event name) and X-Payment-Id (the payment id).
  • Your endpoint should return a 2xx quickly; do slow work asynchronously.

​
Reliability

  • Retries — failed deliveries are retried automatically, up to 5 attempts.
  • At-least-once — the same event may arrive more than once. Make handling idempotent by keying on payment.id + event.
  • Ordering is not guaranteed — rely on the payment’s current status, not on event order.

​
Verifying authenticity

Project webhook endpoints (registered in the dashboard) are signed. Each endpoint has its own signing secret; every delivery carries an x-orqex-signature header containing the HMAC-SHA256 of the raw request body, computed with that secret. Recompute it and compare before trusting the payload: 
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ORQEX_SIGNATURE'] ?? '';
$secret    = '...'; // the endpoint signing secret (whsec_...), shown in the dashboard

if (! hash_equals(hash_hmac('sha256', $payload, $secret), $signature)) {
    http_response_code(401);
    exit; // reject: invalid signature
}
Per-payment webhooks — those sent to a webhook_url set on a single payment or checkout — are not signed: an ad-hoc URL has no secret attached. For those, re-fetch the resource from the API (e.g. GET /payment/intents/{id}) and act on that authoritative state.

​
Inspecting deliveries

The dashboard keeps outbound webhook logs — each delivery, its response status and body, and the number of attempts — to help you debug your handler.