Webhook Debugging & Troubleshooting
Diagnose and fix webhook delivery issues.
Webhooks power bidirectional sync between Basirah and external systems like Jira and ServiceNow. When delivery fails, this guide helps you diagnose the issue.
Check the delivery log
Basirah logs every inbound and outbound webhook event. Review the delivery log for the integration in question to see which deliveries succeeded and which failed, along with error details.
Inspect failed payloads
For failed deliveries, check the recorded request and response details. Common issues include authentication failures, endpoint URL changes, and payload format mismatches.
Verify network connectivity
Ensure the webhook endpoint is reachable from the sending system. For inbound webhooks (from Jira, ServiceNow, etc.), your Basirah instance needs an HTTPS endpoint accessible to the external system’s infrastructure.
Test with a manual trigger
Most integrations support sending a test webhook. Use this to verify end-to-end connectivity without waiting for a real event.
Review retry behavior
Failed webhook deliveries are retried automatically with increasing delays between attempts. If all retries are exhausted, the delivery is marked as failed. You can manually re-trigger failed deliveries from the delivery log.
Common issues
- 401/403 responses — Credentials have expired or been rotated. Update the integration’s authentication settings.
- Timeouts — The receiving endpoint is too slow to respond. Check for performance issues on the receiving side.
- Certificate errors — TLS certificate validation failed. Ensure certificates are valid and not expired.
- Payload too large — The webhook payload exceeds the receiver’s size limit. Check the external system’s configuration.