Let me provide a comprehensive solution for webhook event configuration and troubleshooting:
1. Webhook Event Configuration:
The key issue is understanding how SAP CX integration hub processes and filters events. Here’s the proper setup:
Event Type Selection: OrderStatusChanged is correct, but you need to configure it properly:
- Event Category: Sales Order Events
- Event Type: OrderStatusChanged
- Trigger Condition: Status Transition (not just Status Value)
2. API Event Filtering:
The webhook subscription needs precise filtering using technical status codes:
Find Technical Status Codes:
GET /api/v1/orders/statuses
Response:
[
{"code": "1", "name": "Pending", "displayName": "Pending"},
{"code": "2", "name": "Confirmed", "displayName": "Confirmed"},
{"code": "3", "name": "Shipped", "displayName": "Shipped"}
]
Configure Webhook Filter:
Use the ‘code’ field, not ‘displayName’:
{
"eventType": "OrderStatusChanged",
"filters": {
"statusTransitions": [
{"from": "1", "to": "2"},
{"from": "2", "to": "3"}
]
}
}
3. Order Status Mapping Verification:
Different order types may use different status codes. Verify your specific order lifecycle:
Check Order Type Configuration:
- Navigate to: Administrator → Order Management → Order Types
- Select your order type (e.g., Standard Sales Order)
- View Status Lifecycle diagram
- Note the technical codes for each status node
Common mistakes:
- Using display names instead of codes
- Assuming status codes are consistent across order types
- Not accounting for custom status values added by extensions
4. Webhook Subscription Troubleshooting:
Verify Active Subscription:
GET /api/v1/integration-hub/webhooks/subscriptions
Check that your subscription:
- Status: Active (not Paused or Error)
- Event Count: Shows recent events (indicates events are being generated)
- Last Triggered: Has recent timestamp
- Delivery Success Rate: Above 95%
Common Configuration Issues:
Issue: No events at all
- Cause: Webhook subscription not properly activated
- Solution: Re-activate subscription through integration hub console
- Verify: Check subscription status and event count metrics
Issue: Test events work, real events don’t
- Cause: Event filters too restrictive or using wrong status codes
- Solution: Temporarily remove all filters to test, then add back one by one
- Verify: Monitor integration hub event log for filtered vs. delivered events
Issue: Events delayed or missing
- Cause: Event debouncing or delivery retry failures
- Solution: Check webhook endpoint response times and error rates
- Verify: Ensure endpoint returns 200 OK within 5 seconds
5. Event Processing Behavior:
Understanding Event Debouncing:
The integration hub debounces rapid status changes:
- Default window: 30 seconds
- Behavior: Only last status change in window is sent
- Impact: Intermediate statuses may be skipped
If your order goes: Pending → Processing → Confirmed in under 30 seconds, you’ll only receive the Pending → Confirmed event.
To receive all transitions:
- Option 1: Increase debounce window in webhook config
- Option 2: Subscribe to multiple specific transition events
- Option 3: Use polling API as fallback for critical transitions
Workflow vs. Manual Changes:
Webhook triggers depend on change source:
- Manual UI changes: Always trigger (if filters match)
- API updates: Always trigger (if filters match)
- Workflow automation: May not trigger if workflow is marked as ‘system process’
- Batch updates: Trigger per record but may be debounced
To ensure workflow changes trigger webhooks:
- In workflow configuration, mark as ‘user-initiated process’
- Or use explicit API call at end of workflow to trigger event
6. Recommended Configuration:
For reliable order status notifications:
{
"webhookUrl": "https://fulfillment.example.com/orders/status-changed",
"eventType": "OrderStatusChanged",
"filters": {
"statusTransitions": [
{"from": "1", "to": "2"} // Pending to Confirmed
],
"orderTypes": ["STANDARD_SALES_ORDER"],
"includeWorkflowChanges": true
},
"deliveryConfig": {
"retryAttempts": 3,
"retryDelay": 60,
"timeout": 10
},
"debounceWindow": 0 // Disable debouncing for immediate delivery
}
7. Monitoring and Validation:
Set up proper monitoring:
- Enable webhook delivery logging in integration hub
- Track event generation vs. delivery metrics
- Set up alerts for delivery failures > 5%
- Implement idempotency in receiving system (use order ID + timestamp as key)
Testing Strategy:
- Start with no filters - verify all events are received
- Add status code filter - verify correct filtering
- Test with manual UI change - verify immediate delivery
- Test with API update - verify same behavior
- Test with workflow - verify workflow changes trigger events
- Test rapid status changes - verify debouncing behavior
The most common root cause is using display names instead of technical status codes in the filter configuration. Always query the status codes via API and use the exact code values in your webhook subscription filters.