Skip to main content

Authentication

The OEMSTREAM Webhook API uses API key authentication to secure all endpoints. This guide explains how to authenticate your requests and manage your API keys.

API Key Authentication​

All API requests must include a valid API key in the request headers. The API key identifies your account and determines which resources you can access.

Header Format​

Include your API key in the X-API-Key header:

X-API-Key: your-api-key-here

Example Request​

curl -X POST https://stage-api.oemstream.com/api/webhooks/your-integration-key \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{
    "event": "user.created",
    "data": {
      "user_id": 12345,
      "email": "user@example.com"
    }
  }'

Managing API Keys​

API keys are managed through the OEMSTREAM admin panel. Each integration can have its own API key for better security and access control.

Creating API Keys​

  1. Log in to your OEMSTREAM admin panel
  2. Navigate to Integrations
  3. Create a new integration or edit an existing one
  4. Your API key will be automatically generated
  5. Copy and securely store your API key

API Key Security​

🔒 Security Best Practices

  • Never expose API keys in client-side code or public repositories
  • Use environment variables to store API keys in your applications
  • Rotate keys regularly for enhanced security
  • Use different keys for different environments (development, staging, production)
  • Monitor API key usage through the admin panel

Error Responses​

Invalid API Key​

401 Unauthorized
{
  "error": "Invalid API key",
  "message": "The provided API key is not valid or has been revoked"
}

Missing API Key​

401 Unauthorized
{
  "error": "Missing API key",
  "message": "API key is required in X-API-Key header"
}

Insufficient Permissions​

403 Forbidden
{
  "error": "Insufficient permissions",
  "message": "Your API key does not have permission to access this resource"
}

Code Examples​

PHP (Laravel)​

<?php

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => env('OEMSTREAM_API_KEY'),
    'Content-Type' => 'application/json',
])->post('https://stage-api.oemstream.com/api/webhooks/your-integration-key', [
    'event' => 'order.completed',
    'data' => [
        'order_id' => 67890,
        'total' => 99.99,
        'customer_email' => 'customer@example.com'
    ]
]);

if ($response->successful()) {
    $result = $response->json();
    echo "Webhook sent successfully: " . $result['uuid'];
} else {
    echo "Error: " . $response->body();
}

JavaScript (Node.js)​

const axios = require('axios');

const sendWebhook = async () => {
  try {
    const response = await axios.post(
      'https://stage-api.oemstream.com/api/webhooks/your-integration-key',
      {
        event: 'payment.processed',
        data: {
          payment_id: 'pay_123456',
          amount: 49.99,
          currency: 'USD'
        }
      },
      {
        headers: {
          'X-API-Key': process.env.OEMSTREAM_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Webhook sent:', response.data.uuid);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

sendWebhook();

Python​

import requests
import os

def send_webhook():
    url = "https://stage-api.oemstream.com/api/webhooks/your-integration-key"
    headers = {
        "X-API-Key": os.getenv("OEMSTREAM_API_KEY"),
        "Content-Type": "application/json"
    }
    data = {
        "event": "subscription.renewed",
        "data": {
            "subscription_id": "sub_789012",
            "customer_id": "cust_345678",
            "next_billing_date": "2025-02-10"
        }
    }
    
    try:
        response = requests.post(url, json=data, headers=headers)
        response.raise_for_status()
        result = response.json()
        print(f"Webhook sent successfully: {result['uuid']}")
    except requests.exceptions.RequestException as e:
        print(f"Error sending webhook: {e}")

send_webhook()

Next Steps​

Now that you understand authentication, you're ready to: