How can we help?

Webhook and external API connection failures can occur when systems cannot communicate successfully or when a receiving service rejects a request. Troubleshooting should begin by identifying the direction of the connection and the operation that failed. What is a webhook? A webhook is an HTTP-based mechanism that allows one system to send information to another when a particular event occurs. What is an external API request? An API request is a structured communication between applications. Depending on the integration, a request may retrieve information or ask the external service to perform an authorized operation. Common causes of webhook failures 1. Incorrect endpoint URLs. 2. Invalid or missing authentication. 3. Signature verification failures. 4. Network connectivity problems. 5. Request timeouts. 6. Unsupported HTTP methods. 7. Invalid request payloads. 8. Provider-side delivery failures. 9. Receiving endpoint errors. 10. Configuration changes that invalidate the connection. Common HTTP error codes 400 Bad Request The receiving service could not process the request because of invalid or missing information. 401 Unauthorized Authentication is missing or invalid. 403 Forbidden The request is not permitted. 404 Not Found The requested endpoint or resource could not be found. 429 Too Many Requests The provider's request limit has been reached. 500 Internal Server Error The receiving service encountered an internal error. 502 Bad Gateway An intermediary received an invalid response from another service. 503 Service Unavailable The service is temporarily unavailable. 504 Gateway Timeout An intermediary did not receive a timely response. How to troubleshoot an API connection Step 1: Identify the request direction. Determine whether Polyosync is communicating with an external API or whether an external service is sending information to a configured endpoint. Step 2: Verify the endpoint. Confirm that the destination URL is correct and currently available. Step 3: Review authentication requirements. Check whether the provider requires an API key, OAuth authorization, signature, or another authentication method. Step 4: Verify the request format. Confirm that the HTTP method, headers, and payload match the provider's requirements. Step 5: Review the response. Use the status code and error message to identify the failure. Step 6: Check network and service availability. Determine whether the destination can be reached. Step 7: Review provider restrictions. Check request quotas, account permissions, and endpoint limitations. Step 8: Test with controlled data. Avoid using sensitive production records during initial troubleshooting. Step 9: Confirm the resulting action. Verify whether the destination actually processed the request. What if a webhook is delivered more than once? Some webhook providers use at-least-once delivery, meaning duplicate deliveries are possible. Receiving systems should account for duplicate events where applicable. What if a request times out? A timeout does not always mean that the destination failed to process the operation. Before retrying an action that modifies data, verify whether the external operation completed. Are webhook signatures important? Yes. Where supported, signature verification helps confirm that a webhook originated from the expected provider and that its contents were not altered. Do not disable authentication or signature verification merely to make a failing connection work. Does Polyosync support every webhook delivery pattern? No such assumption should be made. Available endpoints, authentication mechanisms, retry behavior, and event handling depend on the implemented integration. Recommended approach Use the exact error response, provider documentation, and available execution information to identify the failure before modifying credentials or repeating operations.