Connecting NICE Cognigy.AI to Legacy ERP Systems Using Go

What You Will Build

• A Go webhook service that intercepts Cognigy.AI order lookup intents, authenticates to a legacy ERP via SOAP with WS-Security, retrieves order data, parses XML responses into flat JSON, handles network failures with exponential backoff and jitter, maps ERP fields to Cognigy slot variables, and updates dialog state via the REST API to continue the conversation flow.
• This tutorial uses the Cognigy.AI Dialog State REST API and standard HTTP/SOAP endpoints.
• The programming language covered is Go 1.21+.

Prerequisites

• Cognigy.AI API token with dialog:read and dialog:write permissions
• Go 1.21 or later
• Standard library packages: net/http, encoding/json, encoding/xml, math/rand, time, fmt, log, context, io, strings
• Legacy ERP SOAP endpoint URL and WS-Security credentials (username and password)
• A configured Cognigy.AI webhook node pointing to your deployed Go service

Authentication Setup

Cognigy.AI external integrations authenticate using Bearer tokens issued through the platform API key system. The token must carry the dialog:read and dialog:write permissions to modify conversation state. The legacy ERP requires WS-Security UsernameToken authentication embedded directly in the SOAP envelope header.

package main

import (
	"crypto/rand"
	"encoding/json"
	"encoding/xml"
	"fmt"
	"io"
	"log"
	"math"
	"net/http"
	"os"
	"strings"
	"time"
)

// CognigyAuth holds platform credentials
type CognigyAuth struct {
	BaseURL string // e.g., https://tenant.cognigy.ai
	Token   string
}

// ERPCredentials holds WS-Security and endpoint details
type ERPCredentials struct {
	SOAPEndpoint string
	Username     string
	Password     string
}

Store the Cognigy token and ERP credentials in environment variables. The Go service validates incoming webhook requests by checking for a shared secret in the X-Webhook-Secret header to prevent unauthorized POST requests.

Implementation

Step 1: Initialize the HTTP Server and Webhook Endpoint

The webhook endpoint receives the Cognigy.AI conversation payload. The payload contains the dialogId, current intent, and existing slot values. The service extracts the orderNumber slot and prepares it for the ERP request.

// WebhookRequest represents the incoming Cognigy.AI payload
type WebhookRequest struct {
	DialogID string                 `json:"dialogId"`
	Intent   string                 `json:"intent"`
	Slots    map[string]interface{} `json:"slots"`
}

// WebhookResponse is sent back to Cognigy.AI to acknowledge receipt
type WebhookResponse struct {
	Status string `json:"status"`
}

func handleWebhook(auth CognigyAuth, erp ERPCredentials) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
			return
		}

		secret := r.Header.Get("X-Webhook-Secret")
		if secret != os.Getenv("WEBHOOK_SECRET") {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}

		body, err := io.ReadAll(r.Body)
		if err != nil {
			log.Printf("Failed to read request body: %v", err)
			http.Error(w, "Bad request", http.StatusBadRequest)
			return
		}
		defer r.Body.Close()

		var req WebhookRequest
		if err := json.Unmarshal(body, &req); err != nil {
			log.Printf("Failed to parse JSON: %v", err)
			http.Error(w, "Invalid JSON", http.StatusBadRequest)
			return
		}

		if req.Intent != "lookup_order" {
			log.Printf("Ignoring intent: %s", req.Intent)
			w.Header().Set("Content-Type", "application/json")
			json.NewEncoder(w).Encode(WebhookResponse{Status: "ignored"})
			return
		}

		orderNumber, ok := req.Slots["orderNumber"].(string)
		if !ok || orderNumber == "" {
			log.Printf("Missing orderNumber slot")
			http.Error(w, "Missing orderNumber slot", http.StatusBadRequest)
			return
		}

		log.Printf("Processing order lookup for: %s, Dialog: %s", orderNumber, req.DialogID)

		// Proceed to ERP call and dialog state update
		if err := processOrderLookup(auth, erp, req.DialogID, orderNumber); err != nil {
			log.Printf("Order lookup failed: %v", err)
			http.Error(w, "Internal server error", http.StatusInternalServerError)
			return
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(WebhookResponse{Status: "success"})
	}
}

The endpoint validates the HTTP method, checks the shared secret, parses the JSON payload, and verifies the intent. If the intent matches lookup_order, it extracts the orderNumber slot and delegates to the core processing function.

Step 2: Construct the SOAP Request with WS-Security Headers

Legacy ERP systems typically require SOAP 1.1 envelopes with WS-Security UsernameToken authentication. The header must include the wsse:Security element with soapenv:mustUnderstand="1" to ensure the ERP validates credentials before processing the body.

// SOAPEnvelope defines the XML structure for the ERP request
type SOAPEnvelope struct {
	XMLName xml.Name `xml:"soapenv:Envelope"`
	Xmlns   string   `xml:"xmlns:soapenv,attr"`
	XmlnsWsse string `xml:"xmlns:wsse,attr"`
	XmlnsWsua string `xml:"xmlns:wsu,attr"`
	Header  SOAPHeader `xml:"soapenv:Header"`
	Body    SOAPBody   `xml:"soapenv:Body"`
}

type SOAPHeader struct {
	Security SecurityHeader `xml:"wsse:Security"`
}

type SecurityHeader struct {
	XMLName   xml.Name `xml:"wsse:Security"`
	XMLNS     string   `xml:"xmlns:wsse,attr"`
	MustUnderstand string `xml:"soapenv:mustUnderstand,attr"`
	UsernameToken UsernameToken `xml:"wsse:UsernameToken"`
}

type UsernameToken struct {
	Username string `xml:"wsse:Username"`
	Password Password `xml:"wsse:Password"`
}

type Password struct {
	Value string `xml:",chardata"`
	Type  string `xml:"Type,attr"`
}

type SOAPBody struct {
	GetOrderRequest GetOrderRequest `xml:"GetOrderRequest"`
}

type GetOrderRequest struct {
	OrderNumber string `xml:"OrderNumber"`
}

func buildSOAPEnvelope(orderNumber string, creds ERPCredentials) ([]byte, error) {
	envelope := SOAPEnvelope{
		Xmlns:     "http://schemas.xmlsoap.org/soap/envelope/",
		XmlnsWsse: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
		XmlnsWsua: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd",
		Header: SOAPHeader{
			Security: SecurityHeader{
				XMLNS: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
				MustUnderstand: "1",
				UsernameToken: UsernameToken{
					Username: creds.Username,
					Password: Password{
						Value: creds.Password,
						Type:  "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText",
					},
				},
			},
		},
		Body: SOAPBody{
			GetOrderRequest: GetOrderRequest{
				OrderNumber: orderNumber,
			},
		},
	}

	payload, err := xml.MarshalIndent(envelope, "", "  ")
	if err != nil {
		return nil, fmt.Errorf("failed to marshal SOAP envelope: %w", err)
	}

	// Prepend XML declaration
	xmlPayload := append([]byte(`<?xml version="1.0" encoding="UTF-8"?>\n`), payload...)
	return xmlPayload, nil
}

The struct tags map directly to the WS-Security specification. The PasswordText type indicates clear-text credentials, which matches most legacy ERP configurations. The xml.MarshalIndent call produces a well-formed XML document that the ERP parser can process without namespace resolution errors.

Step 3: Implement Exponential Backoff with Jitter and Execute the Request

Network partitions, ERP maintenance windows, and load balancer resets cause transient 5xx errors. A retry mechanism with exponential backoff and randomized jitter prevents thundering herd scenarios and aligns with cloud-native resilience patterns.

func executeSOAPRequest(endpoint string, payload []byte, maxRetries int, baseDelay time.Duration) (*http.Response, error) {
	client := &http.Client{Timeout: 10 * time.Second}
	var lastErr error

	for attempt := 0; attempt <= maxRetries; attempt++ {
		req, err := http.NewRequest(http.MethodPost, endpoint, strings.NewReader(string(payload)))
		if err != nil {
			return nil, fmt.Errorf("failed to create HTTP request: %w", err)
		}
		req.Header.Set("Content-Type", "text/xml; charset=utf-8")
		req.Header.Set("SOAPAction", `"GetOrder"`)

		resp, err := client.Do(req)
		if err != nil {
			lastErr = fmt.Errorf("HTTP request failed on attempt %d: %w", attempt+1, err)
			log.Printf("%v", lastErr)
		} else {
			// Check for transient server errors
			if resp.StatusCode >= 500 {
				lastErr = fmt.Errorf("ERP returned %d on attempt %d", resp.StatusCode, attempt+1)
				log.Printf("%v", lastErr)
				io.Copy(io.Discard, resp.Body)
				resp.Body.Close()
			} else {
				return resp, nil
			}
		}

		if attempt < maxRetries {
			delay := calculateBackoffWithJitter(attempt, baseDelay)
			log.Printf("Retrying in %v...", delay)
			time.Sleep(delay)
		}
	}

	return nil, fmt.Errorf("max retries exceeded: %w", lastErr)
}

func calculateBackoffWithJitter(attempt int, baseDelay time.Duration) time.Duration {
	// Exponential backoff: baseDelay * 2^attempt
	delay := baseDelay * time.Duration(math.Pow(2, float64(attempt)))
	
	// Cap at 30 seconds
	maxDelay := 30 * time.Second
	if delay > maxDelay {
		delay = maxDelay
	}

	// Add jitter: random value between 0 and delay
	jitter := time.Duration(rand.Float64() * float64(delay))
	return delay + jitter
}

The retry loop caps at maxRetries attempts. The calculateBackoffWithJitter function applies the formula delay = baseDelay * 2^attempt + random(0, delay). This distribution ensures requests spread out over time while respecting the maximum wait threshold. The HTTP client timeout prevents goroutine leaks during DNS failures or TCP hangs.

Step 4: Parse XML Responses into Flat JSON Structures

Legacy ERP SOAP responses nest data inside soapenv:Body and custom namespaces. The Go parser extracts the order details and flattens them into a map for direct slot assignment.

// ERPResponse represents the SOAP response structure
type ERPResponse struct {
	XMLName xml.Name     `xml:"soapenv:Envelope"`
	Body    ERPResponseBody `xml:"soapenv:Body"`
}

type ERPResponseBody struct {
	GetOrderResponse GetOrderResponse `xml:"GetOrderResponse"`
}

type GetOrderResponse struct {
	OrderStatus        string `xml:"OrderStatus"`
	EstimatedDelivery  string `xml:"EstimatedDelivery"`
	TrackingNumber     string `xml:"TrackingNumber"`
	CustomerName       string `xml:"CustomerName"`
}

func parseERPResponse(body []byte) (map[string]string, error) {
	var resp ERPResponse
	if err := xml.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("failed to parse ERP XML response: %w", err)
	}

	flatMap := map[string]string{
		"erpOrderStatus":       resp.Body.GetOrderResponse.OrderStatus,
		"erpEstimatedDelivery": resp.Body.GetOrderResponse.EstimatedDelivery,
		"erpTrackingNumber":    resp.Body.GetOrderResponse.TrackingNumber,
		"erpCustomerName":      resp.Body.GetOrderResponse.CustomerName,
	}

	return flatMap, nil
}

The XML struct tags align with the ERP namespace conventions. The parseERPResponse function returns a flat map[string]string where keys match Cognigy.AI slot naming conventions. This eliminates nested object traversal during dialog state updates.

Step 5: Map ERP Fields to Cognigy Slot Variables and Update Dialog State

Cognigy.AI dialog state updates require a PUT request to the /api/v1/dialogs/{dialogId}/state endpoint. The payload must include the slots object and the nextNode identifier to route the conversation forward.

// DialogStateUpdate represents the Cognigy.AI state update payload
type DialogStateUpdate struct {
	Slots    map[string]string `json:"slots"`
	NextNode string            `json:"nextNode"`
}

func updateCognigyDialogState(auth CognigyAuth, dialogID string, slotMap map[string]string, nextNode string) error {
	payload := DialogStateUpdate{
		Slots:    slotMap,
		NextNode: nextNode,
	}

	jsonBody, err := json.Marshal(payload)
	if err != nil {
		return fmt.Errorf("failed to marshal dialog state payload: %w", err)
	}

	endpoint := fmt.Sprintf("%s/api/v1/dialogs/%s/state", strings.TrimSuffix(auth.BaseURL, "/"), dialogID)
	req, err := http.NewRequest(http.MethodPut, endpoint, strings.NewReader(string(jsonBody)))
	if err != nil {
		return fmt.Errorf("failed to create Cognigy update request: %w", err)
	}

	req.Header.Set("Authorization", "Bearer "+auth.Token)
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 5 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return fmt.Errorf("Cognigy API request failed: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("Cognigy API returned %d: %s", resp.StatusCode, string(body))
	}

	log.Printf("Successfully updated dialog state for: %s", dialogID)
	return nil
}

The PUT request replaces the existing slot values for the active dialog session. The nextNode field instructs the Cognigy.AI engine to jump to the specified flow node after the webhook returns. The Bearer token must carry dialog:write permissions, otherwise the platform returns a 403 Forbidden response.

Complete Working Example

package main

import (
	"crypto/rand"
	"encoding/json"
	"encoding/xml"
	"fmt"
	"io"
	"log"
	"math"
	"net/http"
	"os"
	"strings"
	"time"
)

// Configuration types
type CognigyAuth struct {
	BaseURL string
	Token   string
}

type ERPCredentials struct {
	SOAPEndpoint string
	Username     string
	Password     string
}

// Webhook types
type WebhookRequest struct {
	DialogID string                 `json:"dialogId"`
	Intent   string                 `json:"intent"`
	Slots    map[string]interface{} `json:"slots"`
}

type WebhookResponse struct {
	Status string `json:"status"`
}

// SOAP types
type SOAPEnvelope struct {
	XMLName     xml.Name     `xml:"soapenv:Envelope"`
	Xmlns       string       `xml:"xmlns:soapenv,attr"`
	XmlnsWsse   string       `xml:"xmlns:wsse,attr"`
	XmlnsWsua   string       `xml:"xmlns:wsu,attr"`
	Header      SOAPHeader   `xml:"soapenv:Header"`
	Body        SOAPBody     `xml:"soapenv:Body"`
}

type SOAPHeader struct {
	Security SecurityHeader `xml:"wsse:Security"`
}

type SecurityHeader struct {
	XMLName        xml.Name        `xml:"wsse:Security"`
	XMLNS          string          `xml:"xmlns:wsse,attr"`
	MustUnderstand string          `xml:"soapenv:mustUnderstand,attr"`
	UsernameToken  UsernameToken   `xml:"wsse:UsernameToken"`
}

type UsernameToken struct {
	Username string `xml:"wsse:Username"`
	Password Password `xml:"wsse:Password"`
}

type Password struct {
	Value string `xml:",chardata"`
	Type  string `xml:"Type,attr"`
}

type SOAPBody struct {
	GetOrderRequest GetOrderRequest `xml:"GetOrderRequest"`
}

type GetOrderRequest struct {
	OrderNumber string `xml:"OrderNumber"`
}

// ERP Response types
type ERPResponse struct {
	XMLName xml.Name        `xml:"soapenv:Envelope"`
	Body    ERPResponseBody `xml:"soapenv:Body"`
}

type ERPResponseBody struct {
	GetOrderResponse GetOrderResponse `xml:"GetOrderResponse"`
}

type GetOrderResponse struct {
	OrderStatus       string `xml:"OrderStatus"`
	EstimatedDelivery string `xml:"EstimatedDelivery"`
	TrackingNumber    string `xml:"TrackingNumber"`
	CustomerName      string `xml:"CustomerName"`
}

// Dialog state type
type DialogStateUpdate struct {
	Slots    map[string]string `json:"slots"`
	NextNode string            `json:"nextNode"`
}

func buildSOAPEnvelope(orderNumber string, creds ERPCredentials) ([]byte, error) {
	envelope := SOAPEnvelope{
		Xmlns:     "http://schemas.xmlsoap.org/soap/envelope/",
		XmlnsWsse: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
		XmlnsWsua: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd",
		Header: SOAPHeader{
			Security: SecurityHeader{
				XMLNS: "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
				MustUnderstand: "1",
				UsernameToken: UsernameToken{
					Username: creds.Username,
					Password: Password{
						Value: creds.Password,
						Type:  "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText",
					},
				},
			},
		},
		Body: SOAPBody{
			GetOrderRequest: GetOrderRequest{
				OrderNumber: orderNumber,
			},
		},
	}

	payload, err := xml.MarshalIndent(envelope, "", "  ")
	if err != nil {
		return nil, fmt.Errorf("failed to marshal SOAP envelope: %w", err)
	}
	return append([]byte(`<?xml version="1.0" encoding="UTF-8"?>\n`), payload...), nil
}

func calculateBackoffWithJitter(attempt int, baseDelay time.Duration) time.Duration {
	delay := baseDelay * time.Duration(math.Pow(2, float64(attempt)))
	maxDelay := 30 * time.Second
	if delay > maxDelay {
		delay = maxDelay
	}
	jitter := time.Duration(rand.Float64() * float64(delay))
	return delay + jitter
}

func executeSOAPRequest(endpoint string, payload []byte, maxRetries int, baseDelay time.Duration) (*http.Response, error) {
	client := &http.Client{Timeout: 10 * time.Second}
	var lastErr error

	for attempt := 0; attempt <= maxRetries; attempt++ {
		req, err := http.NewRequest(http.MethodPost, endpoint, strings.NewReader(string(payload)))
		if err != nil {
			return nil, fmt.Errorf("failed to create HTTP request: %w", err)
		}
		req.Header.Set("Content-Type", "text/xml; charset=utf-8")
		req.Header.Set("SOAPAction", `"GetOrder"`)

		resp, err := client.Do(req)
		if err != nil {
			lastErr = fmt.Errorf("HTTP request failed on attempt %d: %w", attempt+1, err)
			log.Printf("%v", lastErr)
		} else {
			if resp.StatusCode >= 500 {
				lastErr = fmt.Errorf("ERP returned %d on attempt %d", resp.StatusCode, attempt+1)
				log.Printf("%v", lastErr)
				io.Copy(io.Discard, resp.Body)
				resp.Body.Close()
			} else {
				return resp, nil
			}
		}

		if attempt < maxRetries {
			delay := calculateBackoffWithJitter(attempt, baseDelay)
			log.Printf("Retrying in %v...", delay)
			time.Sleep(delay)
		}
	}

	return nil, fmt.Errorf("max retries exceeded: %w", lastErr)
}

func parseERPResponse(body []byte) (map[string]string, error) {
	var resp ERPResponse
	if err := xml.Unmarshal(body, &resp); err != nil {
		return nil, fmt.Errorf("failed to parse ERP XML response: %w", err)
	}

	return map[string]string{
		"erpOrderStatus":       resp.Body.GetOrderResponse.OrderStatus,
		"erpEstimatedDelivery": resp.Body.GetOrderResponse.EstimatedDelivery,
		"erpTrackingNumber":    resp.Body.GetOrderResponse.TrackingNumber,
		"erpCustomerName":      resp.Body.GetOrderResponse.CustomerName,
	}, nil
}

func updateCognigyDialogState(auth CognigyAuth, dialogID string, slotMap map[string]string, nextNode string) error {
	payload := DialogStateUpdate{
		Slots:    slotMap,
		NextNode: nextNode,
	}

	jsonBody, err := json.Marshal(payload)
	if err != nil {
		return fmt.Errorf("failed to marshal dialog state payload: %w", err)
	}

	endpoint := fmt.Sprintf("%s/api/v1/dialogs/%s/state", strings.TrimSuffix(auth.BaseURL, "/"), dialogID)
	req, err := http.NewRequest(http.MethodPut, endpoint, strings.NewReader(string(jsonBody)))
	if err != nil {
		return fmt.Errorf("failed to create Cognigy update request: %w", err)
	}

	req.Header.Set("Authorization", "Bearer "+auth.Token)
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{Timeout: 5 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return fmt.Errorf("Cognigy API request failed: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusNoContent {
		body, _ := io.ReadAll(resp.Body)
		return fmt.Errorf("Cognigy API returned %d: %s", resp.StatusCode, string(body))
	}

	log.Printf("Successfully updated dialog state for: %s", dialogID)
	return nil
}

func processOrderLookup(auth CognigyAuth, erp ERPCredentials, dialogID string, orderNumber string) error {
	payload, err := buildSOAPEnvelope(orderNumber, erp)
	if err != nil {
		return err
	}

	resp, err := executeSOAPRequest(erp.SOAPEndpoint, payload, 3, 2*time.Second)
	if err != nil {
		return fmt.Errorf("ERP request failed: %w", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return fmt.Errorf("failed to read ERP response: %w", err)
	}

	slotMap, err := parseERPResponse(body)
	if err != nil {
		return fmt.Errorf("failed to parse ERP response: %w", err)
	}

	return updateCognigyDialogState(auth, dialogID, slotMap, "display_order_details")
}

func handleWebhook(auth CognigyAuth, erp ERPCredentials) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
			return
		}

		secret := r.Header.Get("X-Webhook-Secret")
		if secret != os.Getenv("WEBHOOK_SECRET") {
			http.Error(w, "Unauthorized", http.StatusUnauthorized)
			return
		}

		body, err := io.ReadAll(r.Body)
		if err != nil {
			log.Printf("Failed to read request body: %v", err)
			http.Error(w, "Bad request", http.StatusBadRequest)
			return
		}
		defer r.Body.Close()

		var req WebhookRequest
		if err := json.Unmarshal(body, &req); err != nil {
			log.Printf("Failed to parse JSON: %v", err)
			http.Error(w, "Invalid JSON", http.StatusBadRequest)
			return
		}

		if req.Intent != "lookup_order" {
			w.Header().Set("Content-Type", "application/json")
			json.NewEncoder(w).Encode(WebhookResponse{Status: "ignored"})
			return
		}

		orderNumber, ok := req.Slots["orderNumber"].(string)
		if !ok || orderNumber == "" {
			http.Error(w, "Missing orderNumber slot", http.StatusBadRequest)
			return
		}

		if err := processOrderLookup(auth, erp, req.DialogID, orderNumber); err != nil {
			log.Printf("Order lookup failed: %v", err)
			http.Error(w, "Internal server error", http.StatusInternalServerError)
			return
		}

		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(WebhookResponse{Status: "success"})
	}
}

func main() {
	auth := CognigyAuth{
		BaseURL: os.Getenv("COGNIGY_BASE_URL"),
		Token:   os.Getenv("COGNIGY_API_TOKEN"),
	}

	erp := ERPCredentials{
		SOAPEndpoint: os.Getenv("ERP_SOAP_ENDPOINT"),
		Username:     os.Getenv("ERP_USERNAME"),
		Password:     os.Getenv("ERP_PASSWORD"),
	}

	if auth.BaseURL == "" || auth.Token == "" || erp.SOAPEndpoint == "" {
		log.Fatal("Missing required environment variables")
	}

	http.HandleFunc("/webhook/cognigy", handleWebhook(auth, erp))
	log.Printf("Server listening on :8080")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		log.Fatalf("Server failed: %v", err)
	}
}

Common Errors & Debugging

Error: 401 Unauthorized on Cognigy.AI State Update

• Cause: The Bearer token lacks the dialog:write permission or has expired.
• Fix: Regenerate the API token in the Cognigy.AI administration console and assign the Dialogs role with write access. Verify the token string matches the environment variable exactly.
• Code adjustment: Add token expiry validation before the PUT request or implement a token refresh handler.

Error: SOAP 403 Forbidden or WS-Security Validation Failed

• Cause: The ERP rejects the UsernameToken due to mismatched password encoding or missing mustUnderstand attribute.
• Fix: Ensure the Password struct uses PasswordText type and the header includes soapenv:mustUnderstand="1". Some ERP systems require base64 encoding; switch to PasswordDigest if the ERP documentation specifies it.
• Code adjustment: Log the raw SOAP payload before transmission to verify namespace declarations.

Error: xml.Unmarshal: expected element type matching GetOrderResponse

• Cause: The ERP returns a different namespace prefix or wraps the response in an additional envelope layer.
• Fix: Inspect the raw XML response using io.ReadAll and adjust the ERPResponse struct tags to match the actual namespace. Use xml.Name to print the root element name during debugging.
• Code adjustment: Add a fallback parser that iterates over xml.Decoder tokens if strict unmarshaling fails.

Error: 429 Too Many Requests from Cognigy.AI

• Cause: Concurrent webhook executions exceed the platform rate limit for dialog state updates.
• Fix: Implement request queuing or batch updates. Add a retry loop with exponential backoff identical to the ERP retry logic, targeting the Cognigy endpoint instead.
• Code adjustment: Wrap updateCognigyDialogState in a retry function that checks resp.StatusCode == 429 and sleeps before retrying.

Official References

• Cognigy.AI Dialog State API Documentation
• WS-Security UsernameToken Specification
• Go net/http Standard Library
• Go encoding/xml Standard Library