.png?fit=max&auto=format&n=EQK5eX9kTD8NzWwA&q=85&s=878008bf159fcc4964d0c0d508b6e400)
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
Payload format issues
If your external service receives the webhook but returns an error, the payload format is usually the problem.Verify the content type
Most APIs expect
application/json. Set the Content-Type header to match what your receiving service requires.Validate your JSON structure
Use a JSON validator to check your payload body. Common mistakes include trailing commas, unquoted keys, and mismatched brackets.
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 Acceptedresponse 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 of401 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 |
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.
Debugging with request and response logs
Hoop logs the request and response for each webhook execution, making it straightforward to pinpoint failures.Open the workflow execution log
Navigate to Automation > Workflows, select the workflow, and open the Execution Logs tab.
Find the failed webhook step
Locate the webhook action in the execution timeline. Failed steps are marked with a red indicator.
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.
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
Can I send webhooks to multiple URLs from one workflow step?
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.
Does Hoop retry failed webhooks automatically?
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.
What HTTP methods does the webhook action support?
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.