Payloads & Metadata

// Basic webhook payload
const payload = {
  user_id: "usr_abc123",
  email: "alice@example.com",
  name: "Alice Johnson",
  created_at: "2026-01-20T10:30:00Z"
};

// Create webhook job with payload
const response = await fetch('https://api.hookmesh.com/v1/webhook-jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    application_id: 'app_xyz789',
    event_type: 'user.created',
    payload: payload
  })
});

{
  "event_id": "evt_abc123def456",
  "event_type": "user.created",
  "application_id": "app_xyz789",
  "timestamp": "2026-01-20T10:30:00.000Z",
  "payload": {
    "user_id": "usr_abc123",
    "email": "alice@example.com",
    "name": "Alice Johnson",
    "created_at": "2026-01-20T10:30:00Z"
  }
}

// ❌ Bad: Embedding large binary data
const payload = {
  order_id: "ord_123",
  invoice_pdf: "JVBERi0xLjQKJeLjz9MKNCAwIG9..." // 500 KB base64 string
};

// ✅ Good: Reference pattern
const payload = {
  order_id: "ord_123",
  invoice_url: "https://api.yourapp.com/v1/orders/ord_123/invoice.pdf",
  invoice_expires_at: "2026-01-27T10:30:00Z"
};

// Consumer fetches the data when needed
async function handleOrderCompleted(webhook) {
  const { order_id, invoice_url } = webhook.payload;

  // Fetch the large file only if needed
  const invoiceResponse = await fetch(invoice_url, {
    headers: {
      'Authorization': `Bearer ${customerApiKey}`
    }
  });

  const invoicePdf = await invoiceResponse.arrayBuffer();
  // Process the PDF...
}

// Create webhook with metadata
const response = await fetch('https://api.hookmesh.com/v1/webhook-jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    application_id: 'app_xyz789',
    event_type: 'order.completed',
    payload: {
      order_id: 'ord_123',
      total: 99.99,
      currency: 'USD'
    },
    metadata: {
      // Metadata for internal tracking (not sent to consumers)
      source: 'mobile_app',
      user_agent: 'iOS App v2.1.0',
      region: 'us-west-2',
      trace_id: 'trace_abc123def456'
    }
  })
});

// Node.js - Creating a webhook with payload and metadata
import fetch from 'node-fetch';

async function notifySubscriptionUpgrade(
  userId: string,
  fromPlan: string,
  toPlan: string,
  traceId: string
) {
  const response = await fetch('https://api.hookmesh.com/v1/webhook-jobs', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.HOOKMESH_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      application_id: 'app_xyz789',
      event_type: 'subscription.upgraded',

      // Payload: data for consumers
      payload: {
        user_id: userId,
        subscription: {
          previous_plan: fromPlan,
          current_plan: toPlan,
          upgraded_at: new Date().toISOString(),
          next_billing_date: getNextBillingDate()
        },
        billing: {
          amount: 49.99,
          currency: 'USD',
          payment_method: 'pm_abc123'
        }
      },

      // Metadata: internal tracking only
      metadata: {
        source: 'billing_service',
        trace_id: traceId,
        upgraded_by: 'user_self_serve',
        feature_flag: 'new_upgrade_flow',
        deployment: 'v2.1.0'
      }
    })
  });

  const job = await response.json();
  console.log(`Webhook created: ${job.id}`);

  return job;
}

// Usage
await notifySubscriptionUpgrade(
  'usr_123',
  'basic',
  'pro',
  'trace_abc123def456'
);

function getNextBillingDate(): string {
  const date = new Date();
  date.setMonth(date.getMonth() + 1);
  return date.toISOString();
}

# Python - Creating a webhook with payload and metadata
import requests
import os
from datetime import datetime, timedelta

def notify_subscription_upgrade(
    user_id: str,
    from_plan: str,
    to_plan: str,
    trace_id: str
):
    response = requests.post(
        'https://api.hookmesh.com/v1/webhook-jobs',
        headers={
            'Authorization': f'Bearer {os.environ["HOOKMESH_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json={
            'application_id': 'app_xyz789',
            'event_type': 'subscription.upgraded',

            # Payload: data for consumers
            'payload': {
                'user_id': user_id,
                'subscription': {
                    'previous_plan': from_plan,
                    'current_plan': to_plan,
                    'upgraded_at': datetime.utcnow().isoformat() + 'Z',
                    'next_billing_date': get_next_billing_date()
                },
                'billing': {
                    'amount': 49.99,
                    'currency': 'USD',
                    'payment_method': 'pm_abc123'
                }
            },

            # Metadata: internal tracking only
            'metadata': {
                'source': 'billing_service',
                'trace_id': trace_id,
                'upgraded_by': 'user_self_serve',
                'feature_flag': 'new_upgrade_flow',
                'deployment': 'v2.1.0'
            }
        }
    )

    job = response.json()
    print(f'Webhook created: {job["id"]}')

    return job

# Usage
notify_subscription_upgrade(
    'usr_123',
    'basic',
    'pro',
    'trace_abc123def456'
)

def get_next_billing_date() -> str:
    next_month = datetime.utcnow() + timedelta(days=30)
    return next_month.isoformat() + 'Z'