Webhooks - Handle Signed Payment Event Callbacks

OwnPay sends HTTP POST requests to your server when payment events occur. Webhooks let you react to events in real time without polling the API.

How webhooks work

Customer pays -> OwnPay processes -> POST to your endpoint
                                       |
                               Verify signature
                                       |
                               Handle event
                                       |
                               Return 200 OK

OwnPay considers delivery successful when your endpoint returns HTTP 2xx within 10 seconds. On failure, it retries with exponential backoff.

Configuring an endpoint

Go to Developers > Webhooks
Click Add Endpoint
Enter your URL: https://your-store.com/webhooks/ownpay
Select events to receive
Copy the Webhook Secret

OwnPay only sends webhooks to HTTPS endpoints. Use ngrok for local development.

Event types

Event	Description
`payment.pending`	Intent created, customer hasn’t paid
`payment.processing`	Gateway confirmed, settlement in progress
`payment.paid`	Payment fully confirmed and settled
`payment.failed`	Payment attempt failed
`payment.cancelled`	Payment cancelled
`payment.refunded`	Full refund issued
`payment.partial_refunded`	Partial refund issued
`link.visited`	Payment link opened by customer
`link.paid`	Payment via link completed

Request format

Headers:

Content-Type: application/json
X-OwnPay-Signature: sha256=<hmac_hex>
X-OwnPay-Timestamp: 1718000000
X-OwnPay-Event: payment.paid

Body:

{
  "event": "payment.paid",
  "created_at": "2024-06-15T10:30:00Z",
  "data": {
    "id": "pi_01j0x8kz7m3wd4b9qfhec5rtg6",
    "status": "paid",
    "amount": 1500,
    "currency": "BDT",
    "description": "Order #1042",
    "customer": {
      "name": "Rahim Uddin",
      "email": "[email protected]"
    },
    "metadata": {
      "order_id": "1042"
    }
  }
}

Signature verification

Always verify webhook signatures before processing any event.

The signature is computed as:

HMAC-SHA256(secret, timestamp + "." + raw_request_body)

PHP verification

$signature = $_SERVER['HTTP_X_OWNPAY_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_OWNPAY_TIMESTAMP'] ?? '';
$rawBody = file_get_contents('php://input');

$secret = getenv('OWNPAY_WEBHOOK_SECRET');
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

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

$event = json_decode($rawBody, true);

Node.js verification

import crypto from 'crypto';

const signature = req.headers['x-ownpay-signature'];
const timestamp = req.headers['x-ownpay-timestamp'];
const rawBody = req.rawBody.toString();

const secret = process.env.OWNPAY_WEBHOOK_SECRET;
const hmac = crypto
  .createHmac('sha256', secret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

if (!crypto.timingSafeEqual(
  Buffer.from(`sha256=${hmac}`),
  Buffer.from(signature)
)) {
  return res.status(401).send('Invalid signature');
}

Idempotency

Webhook delivery is at-least-once. Your handler may receive the same event more than once. Make all handlers idempotent:

function handlePaymentPaid(array $data): void
{
    $orderId = $data['metadata']['order_id'];
    $order = Order::find($orderId);
    
    if ($order->status === 'fulfilled') {
        return; // Already processed
    }
    
    $order->fulfill();
}

Retry schedule

Attempt	Delay
1	5 minutes
2	15 minutes
3	1 hour
4	6 hours
5	12 hours
6	24 hours
7+	Dead-lettered

Testing locally

Use ngrok to expose a local port:

ngrok http 8080
# Use the ngrok URL in OwnPay webhook settings

You can also replay recent events from Developers > Webhooks > Delivery Log.

​How webhooks work

​Configuring an endpoint

​Event types

​Request format

​Signature verification

​PHP verification

​Node.js verification

​Idempotency

​Retry schedule

​Testing locally

How webhooks work

Configuring an endpoint

Event types

Request format

Signature verification

PHP verification

Node.js verification

Idempotency

Retry schedule

Testing locally