Webhook Events

This endpoint should be implemented by the partner to receive real-time event notifications from Payward Embed.

When specific events occur (such as a quote being executed), Payward sends a POST request to your configured webhook URL with event details.

Security

All webhook requests include an X-Signature header containing a timestamped HMAC-SHA256 signature. Partners should verify this signature to ensure the authenticity and integrity of the request.

Signature Header Format

The signature header follows the format:

t={timestamp},v1={signature}

Where:

• t - Unix timestamp (seconds) when the webhook was sent
• v1 - Hex-encoded HMAC-SHA256 signature

Example header:

X-Signature: t=1734567890,v1=5f2b3c4d1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d

Signature Verification

To verify the webhook signature:

1. Extract the timestamp (t) and signature (v1) from the X-Signature header
2. Construct the signed payload by concatenating: {timestamp}.{raw_request_body}
3. Base64-decode your webhook secret (received when registering the webhook)
4. Compute HMAC-SHA256 of the signed payload using the decoded secret
5. Compare the computed signature (hex-encoded) with the v1 value from the header

import crypto from 'crypto';

interface ParsedSignature {
  timestamp: number;
  signatures: string[];
}

// Parse the X-Signature header
function parseSignatureHeader(header: string): ParsedSignature | null {
  let timestamp: number | null = null;
  const signatures: string[] = [];

  for (const part of header.split(',')) {
    if (part.startsWith('t=')) {
      timestamp = parseInt(part.slice(2), 10);
    } else if (part.startsWith('v1=')) {
      signatures.push(part.slice(3));
    }
  }

  if (timestamp === null) return null;
  return { timestamp, signatures };
}

// Verify the webhook signature
function verifyWebhookSignature(
  signatureHeader: string,
  body: string,
  secretBase64: string
): boolean {
  const parsed = parseSignatureHeader(signatureHeader);
  if (!parsed || parsed.signatures.length === 0) {
    return false;
  }

  // Construct signed payload: {timestamp}.{body}
  const signedPayload = `${parsed.timestamp}.${body}`;

  // Decode base64 secret
  const secretBytes = Buffer.from(secretBase64, 'base64');

  // Compute HMAC-SHA256
  const computedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedPayload)
    .digest('hex');

  // Compare with provided signatures (constant-time comparison recommended)
  return parsed.signatures.some(sig => 
    crypto.timingSafeEqual(
      Buffer.from(computedSignature),
      Buffer.from(sig)
    )
  );
}

Timestamp Validation

The timestamp in the signature header indicates when the webhook was sent. To prevent replay attacks, you should:

1. Parse the timestamp from the X-Signature header
2. Compare it against the current time
3. Reject webhooks with timestamps older than your tolerance window (e.g., 5 minutes)

function isTimestampValid(timestamp: number, toleranceSeconds: number = 300): boolean {
  const currentTime = Math.floor(Date.now() / 1000);
  return Math.abs(currentTime - timestamp) <= toleranceSeconds;
}

Event Types

Event Type	Description
custom_order.executed	A custom order has been successfully executed
custom_order.execution_failed	A custom order execution has failed
custom_order.cancelled	A custom order was cancelled
quote.executed	A quote has been successfully executed
quote.execution_failed	A quote execution has failed
quote.cancelled	A quote was cancelled before execution
deposit.status_updated	The status of a deposit has been updated
withdrawal.status_updated	The status of a withdrawal has been updated
user.verified	A user has been verified and can now trade on the platform
user.closed	A user’s account has been permanently closed
user.disabled	A user’s account has been disabled (e.g., due to a trade lock or account suspension)
reward.paid	An Earn reward has been paid to a user
webhook.test	A test event sent via the Test Webhook endpoint

Headers

All webhook requests include these headers:

Header	Description
Content-Type	Always application/json
X-Signature	Timestamped HMAC-SHA256 signature (format: t={timestamp},v1={signature})
X-Webhook-Event	The event type (e.g., quote.executed)
X-Webhook-ID	The webhook configuration ID

POST /webhooks/payward/events

cURL

custom_order_executed

curl --request POST \
  --url https://your-webhook-endpoint.com/webhooks/payward/events \
  --header 'Content-Type: <content-type>' \
  --header 'X-Signature: <x-signature>' \
  --header 'X-Webhook-Event: <x-webhook-event>' \
  --header 'X-Webhook-ID: <x-webhook-id>' \
  --data '
{
  "event_type": "custom_order.executed",
  "iiban": "AA00 TEST EXAM PLE1",
  "id": "AEGXGV-JZ4I2-6QXEJS",
  "timestamp": "2025-01-15T10:30:00.000000000Z",
  "action": {
    "amount": {
      "asset": "USD",
      "amount": "100.00",
      "asset_class": "currency"
    },
    "quote": {
      "asset": "BTC"
    },
    "type": "spend"
  },
  "trigger": {
    "type": "price",
    "base_asset": "BTC",
    "quote_asset": "USD",
    "target_price": "50000.00",
    "condition": "lte"
  }
}
'

Headers

X-Signature · string · required

Timestamped HMAC-SHA256 signature in the format t={timestamp},v1={signature}. Use this to verify the webhook authenticity and prevent replay attacks.

Example:

"t=1734567890,v1=5f2b3c4d1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d"

X-Webhook-Event · string · required

The type of event that triggered this webhook.

Example:

"quote.executed"

X-Webhook-ID · string · required

The ID of the webhook configuration that received this event.

Example:

"WHTEST-XXXXX-EXAMPLE"

Content-Type · enum<string> · required

Available options: application/json

Body

application/json

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Sent when a custom order has been successfully executed. The order's trade action was triggered by the configured price condition and completed without error.

event_type · enum<string> · required

The event type identifier.

Available options: custom_order.executed

Example:

"custom_order.executed"

iiban · string · required

The Internet International Bank Account Number (IIBAN) of the user whose custom order was executed.

Example:

"AA00 TEST EXAM PLE1"

id · string · required

The unique identifier of the custom order (scheduled action ID).

Example:

"AEGXGV-JZ4I2-6QXEJS"

timestamp · string<date-time> · required

The timestamp when the order was executed (ISO-8601 format).

Example:

"2025-01-15T10:30:00.000000000Z"

action · object · required

The trade action configured for the custom order.

Show child attributes

trigger · object · required

The price trigger that initiated the custom order execution.

Show child attributes

Response

200

Webhook received and processed successfully. Return any 2xx status code to acknowledge receipt.