Skip to content

Chapter 2 · API integration

Webhooks and signature verification

Add a webhook endpoint, learn the event types, verify the MirPay-Signature header and understand retries.

4 min read

On this page
  1. Add a webhook endpoint
  2. Events
  3. What the request looks like
  4. Verify the signature
  5. Responding and retries
  6. Legacy callback (v1/v2)

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

  1. Open Developers → Webhooks (in the mode you need — Test or Live).
  2. Click Add endpoint.
  3. Enter the Endpoint URL. In live mode HTTPS only; internal-network and localhost addresses are rejected.
  4. Choose All events or Selected events and click Save.
  5. 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

  1. Split the MirPay-Signature header on commas: t is the timestamp, v1 is the signature (there may be several).
  2. Build the string t + "." + raw_body and compute HMAC-SHA256 (hex) with your secret.
  3. Compare the result with each v1 using a constant-time comparison.
  4. Reject the request if t differs 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 2xx within 10 seconds. Redirects (3xx) are not followed and count as failures. Do heavy work after responding.
  • If no 2xx is 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 marked failed.
  • The same event may arrive more than once — store MirPay-Event-Id and 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.

Was this article helpful?

Didn’t find an answer?

Send a request — a specialist will check your account and reply.