Workflow API callbacks not updating approval status, causing

BPM Pega Platform
, , , , , , , ,
1

Our Pega 8.6 workflow integrates with an external approval system. When managers approve requests in the external system, it’s supposed to send a callback to our Pega API endpoint to update the approval status. However, the callbacks are being received but not updating the workflow cases - they remain stuck in “Pending Approval” status.

Callback endpoint logs show:


POST /prweb/api/v1/cases/AP-WORKFLOW-123/actions/ApprovalCallback
HTTP 200 OK
Payload received but status unchanged

The external system confirms the callback was sent successfully (HTTP 200), but our workflow cases never progress. We’re seeing hundreds of approval requests stuck, causing major delays in procurement and HR processes. Has anyone dealt with callback endpoint configuration issues or payload schema validation problems in Pega API integrations?

2

Authentication is critical here. The external system’s callback probably uses a service account or API key. Make sure that account has operator access in Pega and appropriate privileges to update workflow assignments. Check your authentication profile - it should be configured for OAuth or basic auth with credentials that map to a valid Pega operator. Without proper auth, the API accepts the call but won’t execute privileged operations like updating case status.

3

Good catch - I enabled detailed logging and you’re right about the payload. The external system sends “decision”:“approved” but our case property is “pyWorkParty.ApprovalStatus”. How do I map these fields correctly in the API service configuration?

4

Let me provide a complete solution addressing all three areas causing your callback failures:

1. Callback Endpoint Configuration: Your API endpoint configuration needs proper action mapping. Navigate to your service rule (likely under Integration-Services) and verify:

  • The POST method is mapped to a case action, not just a generic service activity
  • The action should be “UpdateApprovalStatus” or similar, specifically designed to progress the workflow
  • The endpoint URL pattern must include the case ID parameter: `/cases/{caseID}/actions/ApprovalCallback
  • Configure the response to return meaningful status codes (200 for success, 400 for validation failure, 500 for processing errors)

In the Methods & Operations tab, ensure your callback operation explicitly calls the workflow action that moves the assignment forward. Don’t rely on automatic case updates - invoke the specific flow action.

2. Payload Schema Validation: The payload mismatch is your primary issue. Create a dedicated data transform specifically for callback mapping:

Data Transform: MapExternalApprovalCallback


Set .ApprovalDecision = .decision
Set .ApproverID = .approver_email
Set .ApprovalTimestamp = .approved_at
Set .Comments = .approval_notes

In your service rule’s Request Data Transform field, reference this transform. This ensures incoming JSON fields map correctly to Pega case properties regardless of naming differences.

Also implement payload validation:

  • Check that required fields (decision, approver_email) are present
  • Validate decision values (“approved”, “rejected”, “pending”) against allowed values
  • Return HTTP 400 with specific error messages if validation fails
  • Log validation failures for troubleshooting

3. API Authentication: Authentication issues are likely causing silent failures. Configure proper authentication for the callback:

OAuth 2.0 Configuration (recommended):

  • Create an OAuth 2.0 client registration in Pega for the external system
  • Generate client credentials (client_id and client_secret)
  • Configure the external system to obtain bearer tokens before sending callbacks
  • In your API service, set Authentication to “OAuth 2.0” and reference the client registration
  • Ensure the OAuth client is mapped to a Pega operator with WorkflowManager access level

Basic Auth Alternative: If OAuth isn’t feasible, configure basic authentication:

  • Create a dedicated service account operator (e.g., ExtApprovalService)
  • Assign appropriate access group with privileges to update workflow assignments
  • Configure the external system to send Authorization header with base64-encoded credentials
  • In the service rule, set Authentication to “Basic” and validate against the service account

Critical Authorization Check: Even with authentication, verify the authenticated operator has these privileges:

  • pxUpdateAssignment privilege
  • Access to the case type (AP-WORKFLOW)
  • Permission to execute the specific flow action being triggered

Without these, the API accepts the request (HTTP 200) but the underlying activity fails silently.

Testing & Validation: Use Pega’s API testing tools to verify:

  1. Send a test callback with correct authentication headers
  2. Monitor the Tracer to see if the flow action executes
  3. Check the clipboard to verify payload mapping
  4. Confirm the assignment status actually changes

Implementing these three fixes will resolve your stuck approval requests and establish a reliable callback mechanism for your workflow integration.

5

I suspect a payload schema mismatch. Your external system is probably sending the approval data in a format that Pega isn’t recognizing. Check the API service’s data mapping. In Pega 8.6, the callback endpoint needs to receive specific field names that match your case properties. If the external system sends “approvalStatus” but Pega expects “ApprovalDecision”, the payload validates but doesn’t update anything. Enable detailed logging on the service rule to see exactly what data structure is being received.

6

HTTP 200 doesn’t necessarily mean the callback was processed correctly - it just means Pega received the request. Check your service activity logs to see if the callback is actually triggering the intended workflow action. Look for the ApprovalCallback action in your case type - verify it’s properly mapped to update the assignment status. The issue might be that the API is accepting the request but the underlying activity isn’t executing.