Documentation/API Reference/Webhooks

Webhooks

Listen for events on your PayArk account so your integration can automatically trigger reactions.

Webhooks allow you to receive real-time notifications about events that happen in your PayArk account. PayArk sends these notifications to a URL you specify in the Dashboard.

Event Types

EventDescription
payment.successOccurs whenever a payment is successfully confirmed by the provider.
payment.failedOccurs when a payment attempt fails or is declined.

Payload Structure

Each webhook event is sent as a JSON object with the following structure:

Example Payload
{
  "event": "payment.success",
  "data": {
    "id": "pay_123456789",
    "amount": 1000,
    "currency": "NPR",
    "status": "success",
    "metadata": {
      "order_id": "12345"
    }
  }
}

Verifying Signatures

To verify that a webhook was actually sent by PayArk, we include a signature in the X-PayArk-Signature header. This uses an HMAC-SHA256 signature with your project's Webhook Secret.

Using the SDK (Recommended)

The easiest way to verify signatures is using the official PayArk SDK.

<span class="text-purple-400">import</span> { PayArk } <span class="text-purple-400">from</span> <span class="text-green-300">"@payark/sdk"</span>;

<span class="text-gray-500">// Inside your webhook handler</span>
<span class="text-purple-400">const</span> isValid = <span class="text-purple-400">await</span> PayArk.webhooks.<span class="text-blue-400">verify</span>(
  rawBody, <span class="text-gray-500">// Raw string body (not parsed JSON)</span>
  request.headers[<span class="text-green-300">"x-payark-signature"</span>],
  process.env.PAYARK_WEBHOOK_SECRET
);

<span class="text-purple-400">if</span> (!isValid) {
  <span class="text-purple-400">return</span> response.<span class="text-blue-400">status</span>(400).<span class="text-blue-400">send</span>(<span class="text-green-300">"Invalid signature"</span>);
}

<span class="text-gray-500">// Signature valid, process event</span>
<span class="text-purple-400">const</span> event = JSON.<span class="text-blue-400">parse</span>(rawBody);

Manual Verification

If you are not using our SDK, you can manually verify the signature. The header format is:
t=1698765432,v1=afd3...

  1. Extract the timestamp (t) and signature (v1) from the header.
  2. Prepare the signed_payload string: timestamp + "." + raw_body.
  3. Compute an HMAC-SHA256 signature of the signed_payload using your endpoint's secret.
  4. Compare your computed signature with the signature from the header.