Overview

• Keep your backend synchronized with real-time subscription and purchase data

• Set up automated workflows that respond to subscription events

• Send timely communications to subscribers about billing issues or engage with them during unsubscription

Supported events

Webhook Structure

HTTP Headers

Content-Type: application/json
User-Agent: Monetize-Webhooks/1.0
X-Monetize-Signature: sha256=<signature> (if secret key is configured)

Payload Structure

{
  "id": "evt_1234567890_abcdef123", // Unique event identifier
  "type": "payment.completed", // Event type
  "created_at": "2024-01-15T12:30:45.000Z", // Event creation time in ISO 8601 format
  "data": {
    "price": {
      "id": "cus_customer123", // Internal price id
      "unit_amount": 2000, // Amount in cents 
      "interval": "year" // Plan - week, month, year, lifetime
    },
    "customer": {
      "id": "cus_customer123", // acquiring customer id 
      "email": "user@example.com"
    },
    "user": {
      "id": "cus_customer123", // paywall user id 
      "metadata": { // user metadata, settled by paywall.setUserMetadata
	      "some-custom-field": "value" 
      }
    },
    "paywall": {
      "id": "123"
    },
    "acquiring": {
      "id": "acq_456",
      "provider": "stripe"
    },
  }
}

Payment-Specific Fields

"payment": {
  "id": "pi_payment123",
  "status": "succeeded",
}

Subscription-Specific Fields

"subscription": {
  "id": "sub_subscription123",
  "status": "active",
  "current_period_start": "2024-01-15T12:30:45.000Z",
  "current_period_end": "2024-02-15T12:30:45.000Z"
}

Refund-Specific Fields

"refund": {
  "id": "re_refund123",
  "reason": "requested_by_customer",
  "amount": 2999
}

Authentication Verification

Webhook Signature

Signature Verification Examples

Python

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Remove "sha256=" prefix from header
    signature = signature.replace('sha256=', '')

    return hmac.compare_digest(expected_signature, signature)

# Usage
is_valid = verify_webhook_signature(
    request.body,
    request.headers.get('X-Monetize-Signature'),
    'your_webhook_secret'
)

Node.js

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // Remove "sha256=" prefix from header
  signature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(signature)
  );
}

// Usage
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-monetize-signature'],
  'your_webhook_secret'
);

PHP

function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', $payload, $secret);

    // Remove "sha256=" prefix from header
    $signature = str_replace('sha256=', '', $signature);

    return hash_equals($expectedSignature, $signature);
}

// Usage
$isValid = verifyWebhookSignature(
    file_get_contents('php://input'),
    $_SERVER['HTTP_X_MONETIZE_SIGNATURE'],
    'your_webhook_secret'
);

Webhook Processing

Endpoint Requirements

• HTTPS: Webhooks are only sent to HTTPS URLs

• Response Status: Your endpoint should return HTTP status 200-299 for successful processing

• Timeout: Response timeout is 10 seconds

• Idempotency: Be prepared to receive duplicate events

Processing Example

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/monetize', async (req, res) => {
  try {
    // Verify signature
    const signature = req.headers['x-monetize-signature'];
    if (signature && !verifyWebhookSignature(
      JSON.stringify(req.body), 
      signature, 
      'your_secret'
    )) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // Parse data
    const event = req.body;

    // Process event
    switch (event.type) {
      case 'payment.completed':
        await handlePaymentCompleted(event.data);
        break;
      case 'subscription.created':
        await handleSubscriptionCreated(event.data);
        break;
      // ... other events
    }

    res.status(200).json({ status: 'success' });

  } catch (err) {
    console.error(`Webhook error: ${err}`);
    res.status(500).json({ error: 'Internal error' });
  }
});

async function handlePaymentCompleted(data) {
  // Your payment processing logic
  console.log(`Payment completed: ${data.id}`);
  // e.g., activate user access
}

async function handleSubscriptionCreated(data) {
  // Your subscription creation logic
  console.log(`Subscription created: ${data.subscription.id}`);
  // e.g., grant premium features access
}

Retry Mechanism

• Number of attempts: 5 attempts

• Intervals: 5, 10, 20, 40, and 80 minutes

• Retry conditions: HTTP status 5xx or connection timeout

Logging

• Send time

• HTTP response status

• Response body (first 1000 characters)

• Error messages

• Attempt count

FAQ

Security

• Always verify the signature when using a secret key

• Use HTTPS for all webhook URLs

• Don't log full webhook data in plain text

• Restrict access to webhook endpoints

• Validate data before processing

Limitations

• Maximum payload size: 1 MB

• Timeout: 10 seconds

• Maximum webhooks per account: 10

• Log retention: 30 days

Support

• Webhook ID

• Event time

• Expected behavior

• Actual behavior

• Your side logs (if available)