Webhook Events

Complete reference for all webhook events available in Pixlpay. Subscribe to these events to receive real-time notifications when actions occur in your store.

Event Categories

Category	Events	Description
Orders & Payments	`order.received`, `order.refunded`, `payment.failed`	Order lifecycle and payment events
Subscriptions	`subscription.created`, `subscription.renewed`, `subscription.cancelled`, `subscription.payment_failed`	Recurring payment events
Customers	`customer.created`	Customer account events
Delivery	`delivery.completed`, `delivery.failed`	Item delivery events
Support	`ticket.created`, `ticket.reply`	Support ticket events
Disputes	`dispute.created`, `dispute.resolved`	Chargeback and dispute events
Products	`product.created`, `product.updated`, `product.deleted`	Product management events

Webhook Payload Structure

All webhook payloads follow this structure:

json

{
  "id": "wh_del_abc123",
  "event_type": "order.received",
  "created_at": "2025-01-20T14:30:00.000000Z",
  "data": {
    // Event-specific data
  }
}

Common Headers

Header	Description
`Content-Type`	`application/json`
`User-Agent`	`Prism-Webhooks/1.0`
`X-Webhook-Signature`	HMAC-SHA256 signature (custom webhooks only)
`X-Webhook-Event`	Event type (custom webhooks only)
`X-Webhook-ID`	Unique delivery ID (custom webhooks only)

Order Events

order.received

Triggered when a new order is completed and payment is received. This is the primary event for order notifications.

When triggered:

Customer completes checkout and payment is successful
Order status changes to processing or completed

json

{
  "id": "wh_del_abc123",
  "event_type": "order.received",
  "created_at": "2025-01-20T14:30:00.000000Z",
  "data": {
    "id": 12345,
    "tenant_id": "store_abc123",
    "user_id": 456,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+1234567890",
    "billing_address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "shipping_address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "subtotal": "29.99",
    "tax": "0.00",
    "total": "29.99",
    "currency": "USD",
    "status": "processing",
    "payment_status": "paid",
    "payment_gateway": "stripe",
    "gateway_payment_id": "pi_1234567890",
    "paid_at": "2025-01-20T14:30:00.000000Z",
    "is_test_order": false,
    "metadata": {},
    "payment_method": "Stripe",
    "payment_gateway_icon": "stripe.svg",
    "items": [
      {
        "id": 789,
        "product_id": 101,
        "product_name": "VIP Rank",
        "quantity": 1,
        "unit_price": "29.99",
        "total": "29.99",
        "delivery_status": "pending"
      }
    ],
    "created_at": "2025-01-20T14:30:00.000000Z",
    "updated_at": "2025-01-20T14:30:00.000000Z"
  }
}

order.refunded

Triggered when an order is refunded (full or partial).

When triggered:

Store owner processes a refund
Automatic refund from payment gateway

json

{
  "id": "wh_del_def456",
  "event_type": "order.refunded",
  "created_at": "2025-01-21T10:00:00.000000Z",
  "data": {
    "id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "refund_amount": "29.99",
    "original_total": "29.99",
    "currency": "USD",
    "status": "refunded",
    "payment_status": "refunded",
    "reason": "Customer request",
    "refunded_at": "2025-01-21T10:00:00.000000Z"
  }
}

payment.failed

Triggered when a payment attempt fails.

When triggered:

Card declined during checkout
Insufficient funds
Payment authentication failure
Gateway processing error

json

{
  "id": "wh_del_ghi789",
  "event_type": "payment.failed",
  "created_at": "2025-01-20T14:31:00.000000Z",
  "data": {
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "amount": "29.99",
    "currency": "USD",
    "payment_gateway": "stripe",
    "error_code": "card_declined",
    "error_message": "Your card was declined. Please try a different payment method.",
    "failed_at": "2025-01-20T14:31:00.000000Z"
  }
}

Subscription Events

subscription.created

Triggered when a new subscription is created.

When triggered:

Customer purchases a subscription product
Initial subscription payment succeeds

json

{
  "id": "wh_del_jkl012",
  "event_type": "subscription.created",
  "created_at": "2025-01-20T14:30:00.000000Z",
  "data": {
    "id": 567,
    "tenant_id": "store_abc123",
    "customer_id": 456,
    "product_id": 102,
    "order_id": 12345,
    "status": "active",
    "payment_gateway": "stripe",
    "gateway_subscription_id": "sub_1234567890",
    "gateway_customer_id": "cus_1234567890",
    "gateway_plan_id": "price_1234567890",
    "quantity": 1,
    "current_period_start": "2025-01-20T00:00:00.000000Z",
    "current_period_end": "2025-02-20T00:00:00.000000Z",
    "cancel_at_period_end": false,
    "trial_starts_at": null,
    "trial_ends_at": null,
    "metadata": {},
    "customer": {
      "id": 456,
      "email": "player@example.com",
      "name": "John Doe"
    },
    "product": {
      "id": 102,
      "name": "VIP Monthly",
      "price": "9.99",
      "billing_interval": "month"
    },
    "created_at": "2025-01-20T14:30:00.000000Z",
    "updated_at": "2025-01-20T14:30:00.000000Z"
  }
}

subscription.renewed

Triggered when a subscription payment succeeds and the subscription renews.

When triggered:

Recurring payment processes successfully
Subscription period is extended

json

{
  "id": "wh_del_mno345",
  "event_type": "subscription.renewed",
  "created_at": "2025-02-20T00:01:00.000000Z",
  "data": {
    "id": 567,
    "customer_id": 456,
    "product_id": 102,
    "status": "active",
    "payment_gateway": "stripe",
    "gateway_subscription_id": "sub_1234567890",
    "amount": "9.99",
    "currency": "USD",
    "current_period_start": "2025-02-20T00:00:00.000000Z",
    "current_period_end": "2025-03-20T00:00:00.000000Z",
    "renewed_at": "2025-02-20T00:01:00.000000Z",
    "next_billing_date": "2025-03-20",
    "customer": {
      "id": 456,
      "email": "player@example.com",
      "name": "John Doe"
    },
    "product": {
      "id": 102,
      "name": "VIP Monthly",
      "price": "9.99"
    }
  }
}

subscription.cancelled

Triggered when a subscription is cancelled.

When triggered:

Customer cancels their subscription
Store owner cancels a subscription
Subscription is cancelled due to repeated payment failures

json

{
  "id": "wh_del_pqr678",
  "event_type": "subscription.cancelled",
  "created_at": "2025-01-25T10:00:00.000000Z",
  "data": {
    "id": 567,
    "customer_id": 456,
    "product_id": 102,
    "status": "canceled",
    "payment_gateway": "stripe",
    "gateway_subscription_id": "sub_1234567890",
    "cancel_at_period_end": true,
    "canceled_at": "2025-01-25T10:00:00.000000Z",
    "current_period_end": "2025-02-20T00:00:00.000000Z",
    "ends_at": "2025-02-20",
    "reason": "Customer requested cancellation",
    "customer": {
      "id": 456,
      "email": "player@example.com",
      "name": "John Doe"
    },
    "product": {
      "id": 102,
      "name": "VIP Monthly"
    }
  }
}

subscription.payment_failed

Triggered when a subscription renewal payment fails.

When triggered:

Card expired or declined during renewal
Insufficient funds for recurring payment
Payment method no longer valid

json

{
  "id": "wh_del_stu901",
  "event_type": "subscription.payment_failed",
  "created_at": "2025-02-20T00:05:00.000000Z",
  "data": {
    "id": 567,
    "customer_id": 456,
    "product_id": 102,
    "status": "past_due",
    "payment_gateway": "stripe",
    "gateway_subscription_id": "sub_1234567890",
    "amount": "9.99",
    "currency": "USD",
    "error_code": "card_declined",
    "error_message": "Your card was declined",
    "attempt_count": 1,
    "next_retry_at": "2025-02-23T00:00:00.000000Z",
    "customer": {
      "id": 456,
      "email": "player@example.com",
      "name": "John Doe"
    },
    "product": {
      "id": 102,
      "name": "VIP Monthly"
    },
    "failed_at": "2025-02-20T00:05:00.000000Z"
  }
}

Customer Events

customer.created

Triggered when a new customer account is created.

When triggered:

Customer registers an account
Guest checkout creates a new customer record
OAuth authentication creates a new customer (Discord, Steam)

json

{
  "id": "wh_del_vwx234",
  "event_type": "customer.created",
  "created_at": "2025-01-20T14:30:00.000000Z",
  "data": {
    "id": 456,
    "tenant_id": "store_abc123",
    "email": "player@example.com",
    "name": "John Doe",
    "country": "US",
    "country_name": "United States",
    "discord_id": "123456789012345678",
    "discord_username": "player#1234",
    "steam_id": null,
    "steam_username": null,
    "referral_code": "PLAYER123",
    "referred_by_customer_id": null,
    "created_at": "2025-01-20T14:30:00.000000Z"
  }
}

Delivery Events

delivery.completed

Triggered when item delivery is successful.

When triggered:

RCON command executed successfully on game server
Discord role assigned successfully
Digital asset download link generated
All items in an order have been delivered

json

{
  "id": "wh_del_yz0567",
  "event_type": "delivery.completed",
  "created_at": "2025-01-20T14:35:00.000000Z",
  "data": {
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "delivery_type": "rcon",
    "items": [
      {
        "product_id": 101,
        "product_name": "VIP Rank",
        "quantity": 1,
        "delivery_status": "delivered",
        "delivered_at": "2025-01-20T14:35:00.000000Z"
      }
    ],
    "server": {
      "id": 1,
      "name": "Main Server"
    },
    "completed_at": "2025-01-20T14:35:00.000000Z"
  }
}

delivery.failed

Triggered when item delivery fails.

When triggered:

RCON command fails to execute
Discord role assignment fails
Game server is unreachable
Player not found on server

json

{
  "id": "wh_del_abc890",
  "event_type": "delivery.failed",
  "created_at": "2025-01-20T14:36:00.000000Z",
  "data": {
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "delivery_type": "rcon",
    "items": [
      {
        "product_id": 101,
        "product_name": "VIP Rank",
        "quantity": 1,
        "delivery_status": "failed"
      }
    ],
    "error": "Connection refused: Unable to reach game server",
    "error_code": "RCON_CONNECTION_FAILED",
    "attempt_count": 3,
    "server": {
      "id": 1,
      "name": "Main Server"
    },
    "failed_at": "2025-01-20T14:36:00.000000Z"
  }
}

Support Events

ticket.created

Triggered when a new support ticket is opened.

When triggered:

Customer creates a support ticket
New support request submitted via storefront

json

{
  "id": "wh_del_def123",
  "event_type": "ticket.created",
  "created_at": "2025-01-20T15:00:00.000000Z",
  "data": {
    "ticket_id": 789,
    "subject": "Order not delivered",
    "message": "I purchased VIP rank but haven't received it yet. My order number is ORD-A1B2C3D4E5.",
    "priority": "normal",
    "status": "open",
    "category": "orders",
    "customer_id": 456,
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "created_at": "2025-01-20T15:00:00.000000Z"
  }
}

ticket.reply

Triggered when a customer replies to a support ticket.

When triggered:

Customer sends a message on an existing ticket
Customer provides additional information

json

{
  "id": "wh_del_ghi456",
  "event_type": "ticket.reply",
  "created_at": "2025-01-20T16:30:00.000000Z",
  "data": {
    "ticket_id": 789,
    "message_id": 1234,
    "subject": "Order not delivered",
    "message": "I tried logging in again but still don't see my VIP rank. Here's a screenshot of my profile.",
    "status": "open",
    "customer_id": 456,
    "customer_email": "player@example.com",
    "customer_name": "John Doe",
    "attachments": [
      {
        "filename": "screenshot.png",
        "url": "https://store.example.com/attachments/abc123.png",
        "size": 245678
      }
    ],
    "replied_at": "2025-01-20T16:30:00.000000Z"
  }
}

Dispute Events

dispute.created

Triggered when a chargeback or payment dispute is opened.

When triggered:

Customer files a chargeback with their bank
Payment dispute opened through payment gateway

json

{
  "id": "wh_del_jkl789",
  "event_type": "dispute.created",
  "created_at": "2025-01-25T09:00:00.000000Z",
  "data": {
    "dispute_id": "dp_1234567890",
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "customer_email": "player@example.com",
    "amount": 2999,
    "currency": "USD",
    "reason": "fraudulent",
    "reason_description": "Customer claims they did not authorize the purchase",
    "status": "needs_response",
    "payment_gateway": "stripe",
    "charge_id": "ch_1234567890",
    "evidence_due_by": "2025-02-05T23:59:59.000000Z",
    "due_by": "2025-02-05",
    "created_at": "2025-01-25T09:00:00.000000Z"
  }
}

Important

Dispute amounts are in cents (smallest currency unit). Divide by 100 to get the actual amount.

dispute.resolved

Triggered when a dispute is resolved (won or lost).

When triggered:

Bank/card issuer makes final decision on dispute
Dispute evidence reviewed and verdict issued

json

{
  "id": "wh_del_mno012",
  "event_type": "dispute.resolved",
  "created_at": "2025-02-10T14:00:00.000000Z",
  "data": {
    "dispute_id": "dp_1234567890",
    "order_id": 12345,
    "order_number": "ORD-A1B2C3D4E5",
    "amount": 2999,
    "currency": "USD",
    "status": "won",
    "reason": "fraudulent",
    "payment_gateway": "stripe",
    "charge_id": "ch_1234567890",
    "net_amount_impact": 0,
    "resolved_at": "2025-02-10T14:00:00.000000Z"
  }
}

Possible status values:

won - Dispute resolved in your favor, funds returned
lost - Dispute resolved in customer's favor, funds deducted
warning_closed - Early warning, no funds affected

Product Events

product.created

Triggered when a new product is created.

When triggered:

Store owner creates a new product
Product created via API

json

{
  "id": "wh_del_pqr345",
  "event_type": "product.created",
  "created_at": "2025-01-20T12:00:00.000000Z",
  "data": {
    "product_id": 103,
    "name": "Diamond Sword",
    "slug": "diamond-sword",
    "description": "A powerful diamond sword for your adventures",
    "price": "14.99",
    "currency": "USD",
    "type": "digital",
    "category": "Weapons",
    "category_id": 5,
    "is_active": true,
    "is_featured": false,
    "stock_quantity": null,
    "stock_enabled": false,
    "created_at": "2025-01-20T12:00:00.000000Z"
  }
}

product.updated

Triggered when a product is updated.

When triggered:

Store owner edits product details
Product updated via API
Price or stock changes

json

{
  "id": "wh_del_stu678",
  "event_type": "product.updated",
  "created_at": "2025-01-21T10:30:00.000000Z",
  "data": {
    "product_id": 103,
    "name": "Diamond Sword",
    "slug": "diamond-sword",
    "price": "12.99",
    "currency": "USD",
    "is_active": true,
    "changes": {
      "price": {
        "old": "14.99",
        "new": "12.99"
      }
    },
    "updated_at": "2025-01-21T10:30:00.000000Z"
  }
}

product.deleted

Triggered when a product is deleted.

When triggered:

Store owner deletes a product
Product deleted via API (soft delete)

json

{
  "id": "wh_del_vwx901",
  "event_type": "product.deleted",
  "created_at": "2025-01-22T09:00:00.000000Z",
  "data": {
    "product_id": 103,
    "name": "Diamond Sword",
    "slug": "diamond-sword",
    "deleted_at": "2025-01-22T09:00:00.000000Z"
  }
}

Legacy Events

The following events are supported for backward compatibility but are deprecated. Use the recommended events instead.

Legacy Event	Recommended Event	Notes
`purchase.completed`	`order.received`	Same payload structure
`order.created`	`order.received`	Fires earlier in the order lifecycle
`order.updated`	`order.received`	Consider using `order.received` for most use cases
`order.completed`	`order.received`	Fires when order is fully delivered

Discord Webhook Format

When using Discord webhooks, Pixlpay automatically formats payloads as Discord embeds:

json

{
  "embeds": [
    {
      "title": "New Order",
      "color": 2278621,
      "timestamp": "2025-01-20T14:30:00.000000Z",
      "footer": {
        "text": "Pixlpay - Your Store Name"
      },
      "fields": [
        {
          "name": "Order Number",
          "value": "ORD-A1B2C3D4E5",
          "inline": true
        },
        {
          "name": "Amount",
          "value": "USD 29.99",
          "inline": true
        },
        {
          "name": "Customer",
          "value": "player@example.com",
          "inline": false
        },
        {
          "name": "Items",
          "value": "- VIP Rank (x1)",
          "inline": false
        }
      ]
    }
  ]
}

Discord-Specific Features

Discord webhooks include:

Color-coded embeds based on event type (green for success, red for failures, etc.)
Emoji indicators in titles
Automatic timestamp formatting
Store name in footer

Event Summary

Event	Description	Trigger
`order.received`	New order completed and paid	Payment successful
`order.refunded`	Order refunded	Refund processed
`payment.failed`	Payment attempt failed	Payment declined
`subscription.created`	New subscription started	First subscription payment
`subscription.renewed`	Subscription renewed	Recurring payment success
`subscription.cancelled`	Subscription cancelled	Customer or store cancellation
`subscription.payment_failed`	Subscription payment failed	Renewal payment declined
`customer.created`	New customer registered	Account created
`delivery.completed`	Items delivered successfully	All items delivered
`delivery.failed`	Item delivery failed	Delivery error
`ticket.created`	New support ticket opened	Customer creates ticket
`ticket.reply`	Customer replied to ticket	New message on ticket
`dispute.created`	Chargeback/dispute opened	Bank dispute initiated
`dispute.resolved`	Dispute resolved (won/lost)	Dispute decision made
`product.created`	Product created	New product added
`product.updated`	Product updated	Product details changed
`product.deleted`	Product deleted	Product removed

Testing Webhooks

Use the "Test Webhook" button in your store settings to send a test payload to your endpoint. Test payloads include a test: true field to identify them.

Development Tools

For local development, use tools like ngrok or localtunnel to expose your local server to receive webhooks.

Webhook Events ​

Event Categories ​

Webhook Payload Structure ​

Common Headers ​

Order Events ​

order.received ​

order.refunded ​

payment.failed ​

Subscription Events ​

subscription.created ​

subscription.renewed ​

subscription.cancelled ​

subscription.payment_failed ​

Customer Events ​

customer.created ​

Delivery Events ​

delivery.completed ​

delivery.failed ​

Support Events ​

ticket.created ​

ticket.reply ​

Dispute Events ​

dispute.created ​

dispute.resolved ​

Product Events ​

product.created ​

product.updated ​

product.deleted ​

Legacy Events ​

Discord Webhook Format ​

Event Summary ​

Testing Webhooks ​

Webhook Events

Event Categories

Webhook Payload Structure

Common Headers

Order Events

order.received

order.refunded

payment.failed

Subscription Events

subscription.created

subscription.renewed

subscription.cancelled

subscription.payment_failed

Customer Events

customer.created

Delivery Events

delivery.completed

delivery.failed

Support Events

ticket.created

ticket.reply

Dispute Events

dispute.created

dispute.resolved

Product Events

product.created

product.updated

product.deleted

Legacy Events

Discord Webhook Format

Event Summary

Testing Webhooks