Table of Contents
Errors, Messages, and Common Fixes #
| Issue / Message | Why It Happens | How to Fix |
|---|---|---|
401 Unauthorized | Missing or invalid token | Check token in Settings; ensure correct Bearer format |
403 Forbidden | Token exists but lacks required scope | Regenerate token in Settings |
400 Bad Request: missing externalEventId | Required field omitted | Include externalEventId in payload |
400 Bad Request: signature invalid | HMAC verification failed | Check signature algorithm; use raw token as HMAC key |
400 Bad Request: timestamp expired | Request timestamp outside allowed window | Sync your server clock; send request immediately after signing |
400 Bad Request: nonce reused | Same nonce sent within replay window | Use a unique nonce per request (UUID or random string) |
429 Too Many Requests | Rate limit hit | Slow down the event stream; implement backoff |
workflowDispatchStatus: feature_disabled | Automation not in plan | Upgrade to Enterprise plan |
workflowDispatchStatus: no_matching_workflows | No active workflows match | Create and activate a matching workflow |
workflowDispatchStatus: rate_limited | Automation rate limit | Wait for the rate limit window to reset |
Diagnosis Flow: Event sent but nothing happened #
- Confirm the external system received a successful response.
- If the response says
duplicate, send a genuinely new event. - If the response says
no_matching_workflows, activate or create a matching workflow. - If the response says
triggered, check workflow execution history for step-level failures. - If WordPress is the source, verify Peikly -> Request Tracking before changing Application configuration.
Diagnosis Flow: WordPress request failed #
- Open Peikly -> Request Tracking.
- Read the HTTP code on the failed row.
- Match it to the next action:
401-> replace the token.403-> confirm token scope/feature access and reconnect.400 signature invalid-> fix the plugin configuration or reconnect using a fresh token.429-> reduce event volume and retry later.5xxor network failure -> the plugin retries on its own; if it keeps failing, check that the WordPress server can reach Application.
- Retry one event only after the underlying cause is fixed.
Best Practices #
- Use a UUID v4 as the
externalEventId— this guarantees uniqueness and deduplication. - Sign requests immediately before sending to avoid timestamp expiry.
- Implement exponential backoff for
429responses. - On specific store-event triggers (for example Cart Abandoned), put Add/Upsert Contact before any step that references contact data. Each event also fires External Integration Event Received, so avoid running both kinds of workflow for the same event (11.8).
- Monitor the webhook monitoring widget on your Home Dashboard for event delivery stats.
