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.

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.

Supported Gateways:

  • stripe – Stripe payment events
  • paypal – PayPal IPN and webhook events
  • generic – Generic webhook adapter for other services

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

Stripe Integration

Endpoint: /webhooks/stripe

Supported Events:

  • payment_intent.succeeded
  • invoice.payment_succeeded
  • checkout.session.completed

Example Request:

curl -X POST "https://yoursite.com/wp-json/odcm/v1/webhooks/stripe" \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1640995200,v1=abc123..." \
  -d '{
    "id": "evt_1ABC123",
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_1ABC123",
        "metadata": {
          "order_id": "789"
        },
        "status": "succeeded"
      }
    }
  }'

Example Response:

{
  "success": true,
  "message": "Webhook processed successfully",
  "data": {
    "event_id": "evt_1ABC123",
    "order_id": 789,
    "rules_triggered": 1,
    "actions_executed": ["complete_order"]
  }
}

PayPal Integration

Endpoint: /webhooks/paypal

Supported Events:

  • PAYMENT.SALE.COMPLETED
  • CHECKOUT.ORDER.APPROVED

Example Request:

curl -X POST "https://yoursite.com/wp-json/odcm/v1/webhooks/paypal" \
  -H "Content-Type: application/json" \
  -H "PayPal-Transmission-Id: abc123" \
  -H "PayPal-Cert-Id: xyz789" \
  -H "PayPal-Transmission-Sig: signature" \
  -d '{
    "event_type": "PAYMENT.SALE.COMPLETED",
    "resource": {
      "id": "PAY-123ABC",
      "custom": "order_789",
      "state": "completed"
    }
  }'

Generic Webhook Adapter

Endpoint: /webhooks/generic

For services not specifically supported, the generic adapter can map webhook payloads to Order Daemon events.

Configuration: Requires mapping rules defined in webhook settings.

Example Request:

curl -X POST "https://yoursite.com/wp-json/odcm/v1/webhooks/generic" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your_shared_secret" \
  -d '{
    "event": "payment.completed",
    "order_reference": "789",
    "amount": "29.99",
    "currency": "USD"
  }'

Webhook Management

GET /webhooks/

List configured webhooks and their status.

Authentication: Requires manage_woocommerce capability.

Example Response:

{
  "success": true,
  "data": {
    "endpoints": [
      {
        "gateway": "stripe",
        "url": "https://yoursite.com/wp-json/odcm/v1/webhooks/stripe",
        "status": "active",
        "events": ["payment_intent.succeeded"],
        "last_received": "2025-01-15T14:30:25Z",
        "success_rate": 98.5
      },
      {
        "gateway": "paypal",
        "url": "https://yoursite.com/wp-json/odcm/v1/webhooks/paypal", 
        "status": "configured",
        "events": ["PAYMENT.SALE.COMPLETED"],
        "last_received": null,
        "success_rate": null
      }
    ]
  }
}

POST /webhooks/test/{gateway}

Test webhook endpoint with sample data.

Authentication: Requires manage_woocommerce capability.

Example Request:

curl -X POST "https://yoursite.com/wp-json/odcm/v1/webhooks/test/stripe" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"order_id": 789}'

Example Response:

{
  "success": true,
  "data": {
    "test_event_sent": true,
    "gateway_response": {
      "processed": true,
      "rules_evaluated": 1,
      "actions_executed": ["complete_order"]
    },
    "audit_entry_id": 458
  }
}

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

Example Response:

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log_123",
        "timestamp": "2025-01-15T14:30:25Z",
        "gateway": "stripe",
        "event_type": "payment_intent.succeeded",
        "status": "success",
        "order_id": 789,
        "processing_time_ms": 125,
        "rules_triggered": 1
      },
      {
        "id": "log_124",
        "timestamp": "2025-01-15T14:25:10Z",
        "gateway": "stripe", 
        "event_type": "payment_intent.succeeded",
        "status": "error",
        "error_message": "Order not found",
        "processing_time_ms": 45
      }
    ],
    "total": 150
  }
}

Webhook Security

Signature Verification

Stripe: Uses Stripe-Signature header with HMAC-SHA256

$signature = $_SERVER['HTTP_STRIPE_SIGNATURE'] ?? '';
$is_valid = \Stripe\Webhook::constructEvent($payload, $signature, $webhook_secret);

PayPal: Uses certificate verification with multiple headers

$transmission_id = $_SERVER['HTTP_PAYPAL_TRANSMISSION_ID'] ?? '';
$cert_id = $_SERVER['HTTP_PAYPAL_CERT_ID'] ?? '';
$transmission_sig = $_SERVER['HTTP_PAYPAL_TRANSMISSION_SIG'] ?? '';

Generic: Supports HMAC-SHA256 shared secrets

$expected = hash_hmac('sha256', $payload, $shared_secret);
$provided = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';
$is_valid = hash_equals($expected, $provided);

IP Whitelisting

Configure allowed IP ranges for webhook sources:

{
  "stripe": ["54.187.174.169", "54.187.205.235"],
  "paypal": ["173.0.81.1/32", "173.0.81.33/32"],
  "custom": ["your.server.ip"]
}

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
  1. Map to Universal Event
  • Convert gateway-specific data to standard format
  • Enrich with order context from WooCommerce
  1. Trigger Rule Evaluation
  • Find applicable rules based on trigger type
  • Evaluate conditions against order data
  • Execute matching actions
  1. Record Audit Trail
  • Log webhook reception and processing
  • Record rule evaluations and outcomes
  • Track performance metrics

Custom Gateway Integration

Creating a Custom Adapter

To integrate a new payment gateway or service:

  1. Implement Gateway Adapter:
class CustomGatewayAdapter extends AbstractGatewayAdapter {
    public function get_id(): string {
        return 'custom_gateway';
    }

    public function process_webhook(array $payload): UniversalEvent {
        // Parse gateway-specific payload
        $order_id = $this->extract_order_id($payload);
        $event_type = $this->map_event_type($payload['event']);

        return new UniversalEvent($event_type, $order_id, $payload);
    }

    public function verify_signature(array $headers, string $payload): bool {
        // Implement signature verification
        return true;
    }
}
  1. Register with Plugin:
add_filter('odcm_gateway_adapters', function($adapters) {
    $adapters[] = new CustomGatewayAdapter();
    return $adapters;
});

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 events: payment_intent.succeeded
  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
  4. Set shared secret for authentication

Error Handling

Common Error Responses

Invalid Signature (401):

{
  "success": false,
  "message": "Webhook signature verification failed",
  "code": "invalid_signature"
}

Order Not Found (404):

{
  "success": false,
  "message": "Order reference not found",
  "code": "order_not_found",
  "data": {
    "order_reference": "789"
  }
}

Processing Error (500):

{
  "success": false,
  "message": "Webhook processing failed",
  "code": "processing_error",
  "data": {
    "error_details": "Rule evaluation timeout"
  }
}

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

Was this article helpful?

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