> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting custom webhook actions in workflows

> Fix webhook action failures in HoopAI platform workflows, including URL validation, payload formatting, timeout errors, and debugging with request and response logs.

Custom webhook actions let you connect your Hoop workflows to external services by sending HTTP requests when specific events occur. When a webhook action fails, workflows stall and downstream processes break. This guide helps you diagnose and resolve the most common webhook issues.

***

## URL validation errors

Webhook URLs must be properly formatted or the action will fail immediately without sending a request.

* Use the full URL including the protocol (`https://`)
* Avoid trailing spaces or invisible characters copied from other applications
* Confirm the endpoint is publicly accessible (localhost and private IPs will not work)
* Check that the URL does not contain unencoded special characters

<Warning>
  Hoop only supports `https://` webhook URLs. HTTP endpoints without SSL will be rejected for security reasons.
</Warning>

***

## Payload format issues

If your external service receives the webhook but returns an error, the payload format is usually the problem.

<Steps>
  <Step title="Verify the content type">
    Most APIs expect `application/json`. Set the **Content-Type** header to match what your receiving service requires.
  </Step>

  <Step title="Validate your JSON structure">
    Use a JSON validator to check your payload body. Common mistakes include trailing commas, unquoted keys, and mismatched brackets.
  </Step>

  <Step title="Check custom value placeholders">
    If you are using custom values (merge fields) in the payload body, confirm they resolve to valid data. An empty or null custom value can produce malformed JSON.
  </Step>
</Steps>

<Tip>
  Wrap custom value placeholders in quotes within your JSON payload to prevent syntax errors when the value is empty. For example, use `"name": "{{contact.first_name}}"` instead of `"name": {{contact.first_name}}`.
</Tip>

***

## Timeout errors

Hoop enforces a timeout on webhook requests. If the external service takes too long to respond, the action will fail.

* The default webhook timeout is **30 seconds**
* If your endpoint requires heavy processing, consider having it return a `202 Accepted` response immediately and process the data asynchronously
* Check your external service logs for slow database queries or resource bottlenecks

***

## Authentication header configuration

Many APIs require authentication headers. Incorrect header configuration is a common source of `401 Unauthorized` and `403 Forbidden` responses.

| Header type  | Format example                                    |
| ------------ | ------------------------------------------------- |
| Bearer token | `Authorization: Bearer your-token-here`           |
| API key      | `x-api-key: your-key-here`                        |
| Basic auth   | `Authorization: Basic base64-encoded-credentials` |

<Note>
  API keys and tokens expire. If a webhook that was previously working starts returning 401 errors, generate a new token from your external service and update the header in Hoop.
</Note>

***

## Debugging with request and response logs

Hoop logs the request and response for each webhook execution, making it straightforward to pinpoint failures.

<Steps>
  <Step title="Open the workflow execution log">
    Navigate to **Automation > Workflows**, select the workflow, and open the **Execution Logs** tab.
  </Step>

  <Step title="Find the failed webhook step">
    Locate the webhook action in the execution timeline. Failed steps are marked with a red indicator.
  </Step>

  <Step title="Review the request details">
    Expand the step to see the full request URL, headers, and body that Hoop sent. Verify these match what your external service expects.
  </Step>

  <Step title="Review the response details">
    Check the HTTP status code and response body returned by the external service. The error message usually indicates what needs to change.
  </Step>
</Steps>

***

## Common HTTP error codes

| Status code | Meaning               | What to do                                                     |
| ----------- | --------------------- | -------------------------------------------------------------- |
| 400         | Bad Request           | Fix the payload format or required fields                      |
| 401         | Unauthorized          | Update your authentication headers                             |
| 403         | Forbidden             | Check API permissions or IP allowlisting                       |
| 404         | Not Found             | Verify the endpoint URL is correct                             |
| 429         | Too Many Requests     | Add a wait step before the webhook or reduce trigger frequency |
| 500         | Internal Server Error | The external service has an issue; check their status page     |
| 502/503     | Service Unavailable   | The external service is temporarily down; retry later          |

***

## FAQs

<AccordionGroup>
  <Accordion title="Can I send webhooks to multiple URLs from one workflow step?">
    No. Each webhook action sends to a single URL. To hit multiple endpoints, add separate webhook actions for each URL in your workflow.
  </Accordion>

  <Accordion title="Does Hoop retry failed webhooks automatically?">
    Hoop does not automatically retry failed webhook actions. If you need retry logic, add a conditional branch after the webhook step that re-sends the request on failure.
  </Accordion>

  <Accordion title="What HTTP methods does the webhook action support?">
    Hoop supports GET, POST, PUT, PATCH, and DELETE methods for custom webhook actions. POST is the default and most commonly used method.
  </Accordion>
</AccordionGroup>