Webhooks and signature verification
Add a webhook endpoint, learn the event types, verify the MirPay-Signature header and understand retries.
On this page
A webhook is an HTTP request MirPay sends to your server when a payment changes status. Rely on webhooks instead of polling lists.
Add a webhook endpoint
- Open Developers → Webhooks (in the mode you need — Test or Live).
- Click Add endpoint.
- Enter the Endpoint URL. In live mode HTTPS only; internal-network and localhost addresses are rejected.
- Choose All events or Selected events and click Save.
- On the endpoint page, click Reveal signing secret, copy the
whsec_…secret and store it on your server.
Up to 10 endpoints per mode. You can also manage endpoints via the API: /api/v3/webhook_endpoints. Live events are sent for all payments of the cashbox, including those created via v2.
The Send test event button sends a webhook.test event to your server — the response shows up under Deliveries.
Events
| Event | Sent when |
|---|---|
payment.succeeded |
The payment succeeded. |
payment.failed |
The payment failed. |
payment.canceled |
The payment was canceled via the API or by the customer. |
payment.expired |
The payment expired. |
New event types may be added later: ignore unknown types but still return 2xx.
What the request looks like
MirPay-Signature: t=<unix>,v1=<hex>
MirPay-Event-Id: evt_...
MirPay-Event-Type: payment.succeeded
MirPay-Delivery-Id: whd_...
Content-Type: application/json
Body (event):
{
"id": "evt_...",
"object": "event",
"type": "payment.succeeded",
"livemode": true,
"created": 1731234567,
"api_version": "2026-11-11",
"data": { "object": { "id": "...", "object": "payment", "status": "succeeded", "...": "..." } }
}
Verify the signature
- Split the
MirPay-Signatureheader on commas:tis the timestamp,v1is the signature (there may be several). - Build the string
t + "." + raw_bodyand compute HMAC-SHA256 (hex) with your secret. - Compare the result with each
v1using a constant-time comparison. - Reject the request if
tdiffers from the current time by more than 300 seconds.
Compute the signature over the raw request body — if your framework re-encodes the JSON, the signature won't match.
<?php
$secret = getenv("MIRPAY_WEBHOOK_SECRET"); // whsec_...
$body = file_get_contents("php://input");
$header = $_SERVER["HTTP_MIRPAY_SIGNATURE"] ?? "";
$t = 0; $sigs = [];
foreach (explode(",", $header) as $pair) {
[$k, $v] = array_pad(explode("=", trim($pair), 2), 2, "");
if ($k === "t") $t = (int) $v;
if ($k === "v1") $sigs[] = $v;
}
$expected = hash_hmac("sha256", $t . "." . $body, $secret);
$valid = $t > 0 && abs(time() - $t) <= 300;
$valid = $valid && array_filter($sigs, fn ($s) => hash_equals($expected, $s));
if (!$valid) { http_response_code(400); exit; }
$event = json_decode($body, true);
if ($event["type"] === "payment.succeeded") {
$payment = $event["data"]["object"];
// $payment["id"], $payment["order_id"], $payment["amount"]
}
http_response_code(200);
Responding and retries
- Respond with any
2xxwithin 10 seconds. Redirects (3xx) are not followed and count as failures. Do heavy work after responding. - If no
2xxis received, the delivery is retried: immediately, then after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h — 8 attempts in total (about 3 days). After that the delivery is markedfailed. - The same event may arrive more than once — store
MirPay-Event-Idand skip duplicates. - Event order is not guaranteed; before a decisive action, re-fetch the object with
GET. - Missed events can be fetched with
GET /api/v3/events(kept for 30 days).
Automatic disabling: if an endpoint has had no successful delivery for 72 hours, it becomes Disabled and stops receiving events. After fixing the problem, click Re-enable on the endpoint page. You can resend an undelivered event manually with Resend.
If your secret leaks, use Roll secret (the old secret stops working immediately).
Legacy callback (v1/v2)
The v1/v2 callback keeps working unchanged and is sent in addition to v3 webhooks. It is a application/x-www-form-urlencoded POST to the Webhook URL from your cashbox settings, signed with the Callback secret key (Virtual cashbox → Details → Keys):
X-MirPay-Kassa-Id: <kassa ID>
X-MirPay-Timestamp: <unix>
X-MirPay-Signature: <hex>
signature = HMAC_SHA256(timestamp + "." + raw_body, callback_secret)
If the callback fails, it is retried up to 5 times — your handler must not fulfil an order twice if the same payid arrives again.