Webhooks API: Stripe, PayPal, & Generic Integration Reference

Order Daemon Docs

Webhooks API

The Webhooks API enables Order Daemon to receive and process events from external services like payment gateways, automation platforms, and third-party integrations. This system supports standard webhooks with comprehensive event routing and processing capabilities.

Base URL

/wp-json/odcm/v1/webhooks/

Authentication: Webhook endpoints use service-specific authentication (signatures, shared secrets) rather than WordPress authentication.

Gateway Webhook Endpoints

POST /webhooks/{gateway}

Receive webhook events from supported payment gateways and services.

Currently Supported Gateways:

  • stripe – Stripe payment events (comprehensive event coverage)
  • paypal – PayPal IPN and webhook events (full lifecycle support)
  • generic – Generic webhook adapter for any other service

URL Format: https://yoursite.com/wp-json/odcm/v1/webhooks/{gateway}

Important Note: While Order Daemon provides specific adapters for Stripe and PayPal, the generic adapter allows integration with ANY payment gateway or external service. The generic adapter is highly flexible and can handle webhooks from Square, WooCommerce Payments, or any custom integration.

Gateway Discovery and Management

GET /webhooks/gateways

Get comprehensive information about all available webhook gateways.

Authentication: Requires manage_woocommerce capability.

Response includes:

  • Gateway name and display information
  • Available event types for each gateway
  • Webhook and test URLs
  • Adapter status and capabilities
  • Gateway-specific metadata

GET /webhooks/test/{gateway}/events

Get available test event types for a specific gateway.

Authentication: Requires manage_woocommerce capability.

Response includes:

  • All supported event types for the gateway
  • Default event type
  • Total number of available event types

Webhook Management

GET /webhooks/

List configured webhooks and their status.

Authentication: Requires manage_woocommerce capability.

Response includes:

  • Gateway configuration details
  • Webhook URLs
  • Status information
  • Event types being monitored
  • Performance metrics

POST /webhooks/test/{gateway}

Test webhook endpoint with sample data.

Authentication: Requires manage_woocommerce capability.

Request Parameters:

  • gateway (string, required) – Gateway identifier
  • event_type (string, optional) – Specific event type to test (default: payment_completed)

Response includes:

  • Test success status
  • Test ID for tracking
  • Gateway and event type tested
  • Webhook processing results
  • Performance metrics
  • Test recommendations
  • Payload summary

GET /webhooks/logs/{gateway}

Get webhook processing logs for debugging.

Authentication: Requires manage_woocommerce capability.

Parameters:

  • gateway (string, required) – Gateway identifier
  • limit (int, optional) – Number of recent entries (default: 20)
  • status (string, optional) – Filter by status: success, error, pending

Response includes:

  • Webhook processing logs
  • Timestamps and gateway information
  • Event types and status
  • Performance data
  • Error messages (if applicable)
  • Total count of available logs

Webhook Security

Signature Verification

Stripe: Uses Stripe-Signature header with HMAC-SHA256 verification
PayPal: Uses certificate verification with multiple headers (PayPal-Transmission-Sig, PayPal-Cert-Id, etc.)
Generic: Supports HMAC-SHA256 shared secrets via X-Webhook-Secret header

IP Whitelisting

Configure allowed IP ranges for webhook sources to enhance security.

Rate Limiting

  • Default: 100 requests per minute per gateway
  • Burst: Up to 10 requests in 10 seconds
  • Blocked IPs: Temporary blocks after repeated failures

Event Processing Flow

  1. Receive Webhook
    • Verify signature/authentication
    • Parse and validate payload
    • Extract order reference
  2. Map to Universal Event
    • Convert gateway-specific data to standard format
    • Enrich with order context from WooCommerce
    • Create hierarchical event types (e.g., payment.stripe.payment_intent.succeeded)
  3. Trigger Rule Evaluation
    • Find applicable rules based on trigger type
    • Evaluate conditions against order data
    • Execute matching actions
  4. Record Audit Trail
    • Log webhook reception and processing
    • Record rule evaluations and outcomes
    • Track performance metrics

Gateway-Specific Features

Stripe Integration

Supported Events:

  • Payment Intent events: payment_intent.succeeded, payment_intent.payment_failed, etc.
  • Charge events: charge.succeeded, charge.failed, charge.dispute.created
  • Subscription events: customer.subscription.created, customer.subscription.updated, etc.
  • Invoice events: invoice.payment_succeeded, invoice.payment_failed
  • Customer events: customer.created, customer.updated
  • Refund events: charge.refunded, refund.created
  • Payout events: payout.created, payout.paid

Features:

  • Comprehensive Stripe webhook support
  • Automatic order lookup by Stripe ID or metadata
  • Subscription lifecycle management
  • Dispute and refund handling
  • Full event type hierarchy preservation

PayPal Integration

Supported Events:

  • Payment events: PAYMENT.SALE.COMPLETED, PAYMENT.SALE.REFUNDED, PAYMENT.SALE.DENIED
  • Subscription events: BILLING.SUBSCRIPTION.CREATED, BILLING.SUBSCRIPTION.CANCELLED
  • Recurring payment events: recurring_payment, recurring_payment_failed
  • Dispute events: dispute_opened, dispute_resolved
  • IPN and webhook support

Features:

  • Both IPN (form-encoded) and webhook (JSON) formats supported
  • Automatic order lookup by transaction ID or custom field
  • Subscription and recurring payment handling
  • PayPal certificate verification
  • Comprehensive IPN event type coverage

Generic Adapter

Supported Events:

  • Payment events: payment_completed, payment_failed, payment_refunded, payment_cancelled
  • Order events: order_completed, order_cancelled, order_updated
  • Subscription events: subscription_created, subscription_cancelled, subscription_renewed
  • Custom events: Any custom event type can be processed

Features:

  • Flexible field mapping for any webhook format
  • Automatic extraction of order IDs, transaction IDs, amounts
  • Event type normalization and mapping
  • Support for nested payload structures
  • Configurable authentication methods
  • Ideal for Square, WooCommerce Payments, or custom integrations

Custom Gateway Integration

Creating a Custom Adapter

To integrate a new payment gateway or service:

  1. Extend AbstractGatewayAdapter:
class CustomGatewayAdapter extends AbstractGatewayAdapter {
    public function __construct() {
        parent::__construct('custom_gateway');
    }

    public function canHandle(array $input): bool {
        // Check if this adapter can handle the input
        return isset($input['payload']['custom_gateway_event']);
    }

    public function normalize(array $input): array {
        $payload = $input['payload'] ?? [];
        $order_id = $this->extractOrderId($payload);
        $event_type = $this->mapEventType($payload['event']);

        $event_data = [
            'eventType' => $event_type,
            'sourceGateway' => 'custom_gateway',
            'primaryObjectType' => 'order',
            'primaryObjectID' => $order_id,
            'transactionID' => $payload['transaction_id'] ?? null,
            'amount' => $payload['amount'] ?? null,
            'currency' => $payload['currency'] ?? 'USD',
            'rawData' => $payload,
        ];

        return [new UniversalEvent($event_data)];
    }

    public function validateAuthenticity(array $input): bool {
        // Implement signature verification
        return $this->validateCustomSignature($input);
    }
}
  1. Register with Plugin:
add_action('odcm_register_gateway_adapters', function($router) {
    $router->registerAdapter(new CustomGatewayAdapter());
});

Webhook Configuration

Gateway Setup

Stripe Configuration:

  1. Create webhook endpoint in Stripe dashboard
  2. Set URL: https://yoursite.com/wp-json/odcm/v1/webhooks/stripe
  3. Select relevant events (payment_intent.succeeded, charge.succeeded, etc.)
  4. Copy webhook secret to Order Daemon settings

PayPal Configuration:

  1. Configure IPN or webhook in PayPal dashboard
  2. Set URL: https://yoursite.com/wp-json/odcm/v1/webhooks/paypal
  3. Enable relevant event types
  4. Download and configure PayPal certificates

Generic Configuration:

  1. Configure webhook in external service
  2. Set URL: https://yoursite.com/wp-json/odcm/v1/webhooks/generic
  3. Configure payload mapping rules (if needed)
  4. Set shared secret for authentication (recommended)

Error Handling

Common Error Scenarios

Invalid Signature: Webhook signature verification failed
Order Not Found: Order reference not found in WooCommerce
Processing Error: Webhook processing failed due to internal error
Invalid Payload: Webhook payload format is invalid
Unauthorized: Missing or invalid authentication credentials

Retry Logic

  • Automatic retries: Failed webhooks are retried with exponential backoff
  • Max retries: 3 attempts over 24 hours
  • Dead letter queue: Permanently failed webhooks are logged for manual review

Integration Examples

JavaScript – Configure Webhook URLs:

// Get webhook URLs for frontend display
wp.apiFetch({
  path: '/odcm/v1/webhooks/'
}).then(response => {
  const endpoints = response.data.endpoints;
  endpoints.forEach(endpoint => {
    console.log(`${endpoint.gateway}: ${endpoint.url}`);
  });
});

PHP – Process Custom Events:

// Trigger custom automation event
$event = new UniversalEvent('custom.payment.verified', $order_id, [
    'verification_method' => 'manual_review',
    'verified_by' => get_current_user_id()
]);

do_action('odcm_process_universal_event', $event);

Performance and Monitoring

Monitoring Metrics

  • Success Rate: Percentage of successfully processed webhooks
  • Processing Time: Average time to process webhook events
  • Error Rate: Rate of webhook processing failures
  • Queue Depth: Number of pending webhook events

Performance Optimization

  • Async Processing: Large webhook payloads processed asynchronously
  • Caching: Gateway adapter responses cached appropriately
  • Database Optimization: Webhook logs use optimized database queries
  • Resource Limits: Processing limits prevent runaway automation

Advanced Features

Universal Events Architecture

Order Daemon uses a Universal Events system that normalizes gateway-specific events into a common format:

{
  "eventType": "payment.stripe.payment_intent.succeeded",
  "sourceGateway": "stripe",
  "channel": "webhook",
  "primaryObjectType": "order",
  "primaryObjectID": 789,
  "transactionID": "pi_1ABC123",
  "status": "succeeded",
  "amount": 29.99,
  "currency": "USD",
  "occurredAt": "2026-01-15T13:28:00+01:00",
  "receivedAt": "2026-01-15T13:28:05+01:00",
  "idempotencyKey": "odcm_stripe_1234567890",
  "rawData": {
    "stripe_webhook_data": {
      "id": "evt_1ABC123",
      "type": "payment_intent.succeeded",
      "data": {
        "object": {
          "id": "pi_1ABC123",
          "amount": 2999,
          "currency": "usd",
          "status": "succeeded"
        }
      }
    }
  }
}

Event Router Architecture

The Event Router intelligently routes webhooks to appropriate adapters:

  1. Adapter Selection: Automatically selects the best adapter for the payload
  2. Authentication: Validates signatures and authenticity
  3. Normalization: Converts to Universal Events format
  4. Entity Resolution: Links events to WooCommerce orders and subscriptions
  5. Async Processing: Events are processed asynchronously for reliability

Testing and Debugging

Comprehensive Testing Tools:

  • Test Event Generation: Generate realistic test payloads for any gateway
  • Event Type Discovery: Discover all supported event types per gateway
  • Detailed Test Reports: Get performance metrics and recommendations
  • Audit Trail Integration: Test events appear in Insight Dashboard

Debugging Features:

  • Detailed Logging: All webhook processing is logged with timestamps and metadata
  • Error Context: Full error details including stack traces (in debug mode)
  • Performance Metrics: Execution times and resource usage
  • Payload Inspection: View raw and processed payload data

What’s Next

Was this article helpful?

  • Loading...
Table of Contents
  • Loading...