Troubleshooting Guide for Custom Webhook Actions in Workflows

Overview

Custom webhook actions let your BizStackPro workflows send data to external tools and APIs in real time. When everything is configured correctly, webhooks can create records, update CRMs, trigger third-party automations, and much more.

If a webhook fails, sends the wrong data, or stops working after changes, use this guide to pinpoint the cause and fix it quickly.

1) Webhook action shows as “Failed” in workflow history

A webhook step is usually marked as Failed when the external API returns an error or BizStackPro cannot reach the endpoint.

How to fix

• Verify the URL: Check for typos, missing slashes, or incorrect paths.
• Confirm the server is online: Ensure the receiving system isn’t down.
• Check the HTTP method: Make sure POST/PUT/PATCH/GET matches the API requirement.

Steps to test the endpoint

1. Copy the exact webhook URL from your workflow action.
2. Use Postman or Insomnia to send a test request.
3. Compare the response status/body to the workflow execution logs.
4. Adjust the endpoint/payload until you get a successful response (typically 2xx).

2) Webhook is not sending the correct data

If fields are blank, mis-mapped, or sending unexpected values, the issue usually comes from the payload body, headers, query parameters, or missing data in the test contact.

Checklist for data mapping

• Reopen the Webhook action in the workflow editor.
• Review the Body section and confirm each field uses the correct contact/custom value.
• Confirm your test contact actually has data in every field you’re sending.
• For JSON payloads, verify the body is valid JSON (quotes/commas/brackets).

Testing the payload

1. Send a test contact through the workflow.
2. Inspect the request received by the external system (logs/request history).
3. Adjust mappings until the external system receives the expected structure and values.

3) Webhook returns 401 or 403 (authentication/permission errors)

HTTP 401 and 403 errors indicate authentication or permission problems. The API is reachable, but it’s refusing the request.

How to fix

• Confirm the API key/token is correct and not expired.
• Verify where the API expects credentials (header vs query parameter).
• Confirm the token/account has permission for the endpoint/resource.

Best practices

• Use environment-specific keys (sandbox vs production) and confirm you’re using the right base URL.
• Rotate tokens periodically and update them inside the webhook action.

4) Webhook returns 400 or 404 (bad request / not found)

HTTP 400 means the API received the request but found something invalid in the structure or data. HTTP 404 means the endpoint or resource could not be found.

Fixing 400 Bad Request

• Validate your JSON body using a JSON validator.
• Confirm required fields are present and data types match (string/number/boolean).
• Check API docs for required parameters and exact field names.

Fixing 404 Not Found

• Confirm the endpoint path matches the API docs exactly (including versioning and trailing slashes).
• Verify you’re using the correct base URL (sandbox vs production, region-specific URL, etc.).

5) Webhook returns 5xx errors or times out

HTTP 5xx errors or timeouts usually indicate a problem on the receiving server, or the endpoint is taking too long to respond.

How to troubleshoot

• Check whether the external API is experiencing downtime or internal errors.
• Reduce payload size/complexity if you’re sending a large dataset.
• Retry with a minimal payload to rule out data-specific validation problems.

If only certain requests fail (for example, a specific contact), compare a successful payload with a failing payload to spot differences.

6) Headers and query parameters don’t seem to apply

Missing or incorrect headers/query parameters can cause authentication failures, routing issues, or unexpected responses.

What to check

• Expand Headers and Query Parameters in the webhook action.
• Match key names/values to the API docs exactly (often case-sensitive).
• Remove trailing spaces or accidental line breaks.

7) Webhook worked once but fails for new contacts

If it works for one contact but fails for others, something likely changed in your data, custom values, or mappings.

Common causes

• A contact/custom field used in the webhook was deleted or renamed.
• A custom value no longer exists or no longer returns data.
• New contacts are missing required data for fields the webhook depends on.

Steps to fix

1. Reopen the webhook action in the workflow.
2. Check each mapped field/custom value to confirm it still exists.
3. Test with a contact that has all required fields populated.
4. Re-save the webhook step and re-test the workflow.