Webhooks

OwnPay sends HTTP POST requests to your server when payment events occur. This page is the canonical reference for webhook verification - every other page that mentions webhooks links here.

Webhook payload format

OwnPay sends webhooks as JSON POST requests with three custom headers:

Content-Type: application/json
X-OwnPay-Signature: sha256=abc123...
X-OwnPay-Timestamp: 1718000000
X-OwnPay-Event: payment.completed

The request body contains the event name, a timestamp, and the event data:

{
  "event": "payment.completed",
  "created_at": "2024-06-15T10:30:00Z",
  "data": {
    "id": "pay_abc123",
    "amount": "1500",
    "currency": "USD",
    "status": "completed",
    "customer": {
      "name": "Rahim Uddin",
      "email": "[email protected]"
    },
    "metadata": {
      "order_id": "1042"
    }
  }
}

Event types

Event	Description
`payment.completed`	Payment fully confirmed and settled
`payment.failed`	Payment attempt declined or errored
`payment.expired`	Customer did not pay within the timeout window
`refund.issued`	Refund initiated to the customer
`refund.completed`	Refund settled at the gateway
`refund.failed`	Refund was rejected by the gateway
`customer.created`	A new customer record was created
`webhook.test`	Test event sent from the Developer Hub

Signature verification

Always verify the webhook signature before processing any event. Skipping verification lets attackers forge events.

How verification works

OwnPay computes an HMAC-SHA256 hash of the raw request body using your webhook secret. The signature header contains sha256= followed by the hex-encoded HMAC.

HMAC-SHA256(webhook_secret, raw_request_body) → hex digest

PHP verification

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

// Prevent replay attacks (reject events older than 5 minutes)
if (abs(time() - $timestamp) > 300) {
    http_response_code(403);
    exit('Timestamp outside tolerance');
}

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

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

$event = json_decode($rawBody, true);
// Process $event...
http_response_code(200);

Node.js verification

import crypto from 'crypto';

function verifyWebhook(req, secret) {
  const signature = req.headers['x-ownpay-signature'];
  const timestamp = parseInt(req.headers['x-ownpay-timestamp'], 10);
  const rawBody = req.rawBody.toString('utf8');

  // Reject timestamps older than 5 minutes
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false;
  }

  const hmac = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const expected = `sha256=${hmac}`;
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Python verification

import hmac
import hashlib
import time
import json

def verify_webhook(signature: str, timestamp: int, raw_body: bytes, secret: str) -> bool:
    # Reject timestamps older than 5 minutes
    if abs(int(time.time()) - timestamp) > 300:
        return False

    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'), raw_body, hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Timestamp and replay attack prevention

Every webhook includes the X-OwnPay-Timestamp header. Your receiver should:

Compare the timestamp against your server’s clock
Reject any event with a timestamp more than 5 minutes old
Optionally store processed event IDs to catch duplicate deliveries within the tolerance window

Idempotency

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

function handlePaymentCompleted(array $data): void
{
    $orderId = $data['metadata']['order_id'] ?? '';
    $order = Order::where('id', $orderId)->first();

    if ($order?->status === 'paid') {
        return; // Already processed
    }

    $order?->update(['status' => 'paid']);
}

Expected response

OwnPay considers delivery successful when your endpoint returns any HTTP 2xx status within 10 seconds. Anything else triggers a retry.

Retry schedule

Attempt	Delay after failure
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours
7+	Dead-lettered (logged, no more retries)

You can inspect and replay failed deliveries from Developers → Webhooks → Delivery Log.

Overview

Merchant API

Mobile API

Admin API

Webhook payload format

Event types

Signature verification

How verification works

PHP verification

Node.js verification

Python verification

Timestamp and replay attack prevention

Idempotency

Expected response

Retry schedule

​Webhook payload format

​Event types

​Signature verification

​How verification works

​PHP verification

​Node.js verification

​Python verification

​Timestamp and replay attack prevention

​Idempotency

​Expected response

​Retry schedule

​Related pages

Webhook payload format

Event types

Signature verification

How verification works

PHP verification

Node.js verification

Python verification

Timestamp and replay attack prevention

Idempotency

Expected response

Retry schedule

Related pages