This guide is here to help you troubleshoot common issues with Custom Webhook Actions inside workflows. These actions are used to send real-time data to external systems using flexible request formats. If your webhooks aren’t triggering properly, failing, or returning unexpected results, this FAQ will walk you through the most common fixes. Each answer includes brief steps so you can easily add helpful visuals if needed.
FAQ: Troubleshooting Custom Webhook Actions
Q1: Why is my webhook action marked as "Failed" in the workflow history?
A1: This usually happens when the external API returns an error or cannot be reached.
How to Fix:
Double-check the URL used in the webhook for typos or invalid endpoints.
Ensure the server you're sending to is online and can handle incoming requests.
Steps:
Copy the webhook URL and test it using a third-party tool (like Postman).
Check the workflow execution history to see the error message returned.
Make sure the server supports the HTTP method (POST, GET, etc.) you selected.
Q2: My webhook is not sending the correct data. What’s wrong?
A2: Incorrect data mapping or missing custom values can cause this issue.
How to Fix:
Review the request body and make sure all fields are correctly mapped.
Use the autocomplete suggestions to pull in the right values from contact records or incoming webhook variables.
Steps:
Go to the webhook step in your workflow.
Expand the body section and recheck each field's value.
Use the {} icon or autocomplete field list to insert accurate variables.
Q3: The receiving server is throttling or rejecting some requests. How do I prevent this?
A3: This happens when you're sending too many requests too quickly, exceeding the server's rate limit.
How to Fix:
Slow down the workflow by using a wait step before the webhook.
Add contacts in batches to avoid overwhelming the server.
Steps:
Insert a Wait Step before the webhook (e.g., 1 min delay).
Space out contact entries into the workflow (avoid bulk adding large lists).
Coordinate with the receiving system to understand rate limits.
Q4: My webhook is working, but the external system isn’t doing anything with the data.
A4: The data may not be in the correct format or structure the receiving system expects.
How to Fix:
Check the API documentation of the system you're sending data to.
Make sure headers (like Content-Type: application/json) and request bodies match their format.
Steps:
1. Under webhook settings, verify the correct headers are used.
2. Ensure you're sending data in the required structure (JSON, query parameters, etc.).
3. Test your webhook with a known working sample request to isolate the issue.
Q5: I’m not seeing any errors, but the webhook action seems to be skipped.
A5: Silent skips can happen if the workflow retries and still fails due to silent rejections from the external API.
How to Fix:
Check if the webhook is configured with authentication and the token/key has expired or is invalid.
Review the retry attempts and response codes in the contact's workflow history.
Steps:
1. Confirm your authorization method is correct (e.g., Bearer Token, Basic Auth).
2. Regenerate or re-enter your credentials.
3. Re-add the contact to the workflow after fixing the issue.
Q6: Can I test the webhook setup before sending live data?
A6: While there isn’t a preview mode, you can create a test contact and send test data through the webhook step.
How to Test:
Use a dummy contact with known values.
Observe the workflow history to ensure the webhook executes successfully and returns the correct response.
Steps:
Create a test contact.
Add that contact to the workflow manually.
Monitor the webhook step’s execution log under workflow history.
Q7: Why aren’t my query parameters or headers being recognized by the external system?
A7: Incorrect formatting or missing key-value pairs can cause this issue.
How to Fix:
Review the Query Parameters and Headers section in your webhook setup.
Make sure each field is filled properly and follows the external system’s expected keys.
Steps:
In the webhook settings, expand Headers and Query Parameters.
Confirm all fields are correctly filled (no extra spaces or missing keys).
Save the workflow and retest using a test contact.
Q8: The webhook worked once, but now it's failing for new contacts. What changed?
A8: A likely cause is updated custom values or deleted fields used in the webhook mapping.
How to Fix:
Review any recent changes made to contact fields, custom values, or the data being sent.
Steps:
1. Reopen the webhook action and double-check all dynamic fields.
2. Make sure those fields still exist and have data on the new contact.
3. Re-save the webhook step and re-test.