GitScrum / Docs

Troubleshooting

Diagnose and fix common GitScrum webhook issues: delivery failures, timeout errors, payload problems, and configuration errors.

Common webhook issues and how to resolve them.

Webhook Not Firing

Endpoint not saved

Symptom: No requests reach your server after configuring a webhook.

Solution:

  1. Verify the status indicator is green in the webhook configuration
  2. Re-enter the URL and press Enter to save
  3. Refresh the page and confirm the URL persists

Wrong project

Symptom: Webhooks work for one project but not another.

Solution: Webhooks are per-project. Verify you configured the endpoint in the correct project's settings.

Pro plan required

Symptom: Webhook configuration appears but endpoints don't activate.

Solution: Webhooks require a Pro plan or above. Check your workspace billing status.

Delivery Failures

Endpoint returns non-2xx status

Symptom: GitScrum shows delivery failure for a webhook.

Solution:

  • Check your server logs for errors
  • Ensure your endpoint returns a 2xx status code (200, 201, 202, 204)
  • Verify the endpoint path matches exactly

Connection timeout

Symptom: Webhook deliveries consistently fail with timeout errors.

Solution:

  • Return 200 immediately before processing (use queue-based processing)
  • Check that your server responds within 30 seconds
  • Verify your server is not blocked by a firewall

SSL/TLS errors

Symptom: HTTPS webhook deliveries fail.

Solution:

  • Ensure your SSL certificate is valid and not expired
  • Verify the certificate chain is complete
  • Check that your server supports TLS 1.2 or higher

Payload Issues

Empty or malformed payload

Symptom: Your endpoint receives the request but the body is empty or cannot be parsed.

Solution:

  • Ensure your server parses application/json content type
  • Add express.json() middleware (Node.js) or equivalent
  • Check that your request parsing library handles the payload size
// Express.js - ensure JSON parsing is enabled
app.use(express.json({ limit: '10mb' }));
# Flask - ensure JSON content type is handled
event = request.get_json(force=True)

Unexpected payload structure

Symptom: Your code fails because expected fields are missing.

Solution:

  • Always check for null values before accessing nested properties
  • Use optional chaining in JavaScript: data?.workflow?.title
  • Validate the payload structure before processing
  • See Payload Format for the complete field reference

Testing Issues

Test button sends but server doesn't receive

Symptom: Clicking the test button shows success but no request arrives at your server.

Solution:

  • Verify your server is publicly accessible (not behind a VPN or local network)
  • Check that the URL is correct including protocol (https://)
  • Try using a request inspection tool like webhook.site to verify delivery
  • If using ngrok, ensure the tunnel is still active

Test works but real events don't fire

Symptom: Test payloads arrive but actual events don't trigger webhooks.

Solution:

  • Verify the specific event is configured (test sends to the specific endpoint)
  • Check that the action you're performing matches the event type
  • Ensure you're performing the action in the correct project

Permission Issues

Cannot access webhook settings

Symptom: The Webhooks tab is not visible or settings are read-only.

Solution:

  • Only Manager and Owner roles can configure webhooks
  • Contact your project manager or workspace owner for access

Debugging Tips

Use webhook.site for inspection

Test your webhook configuration using webhook.site:

  1. Go to webhook.site and copy the unique URL
  2. Paste it as the endpoint in GitScrum webhooks
  3. Trigger an event or click Test
  4. Inspect the full request details on webhook.site

Check delivery logs

GitScrum logs every webhook delivery attempt including:

  • Endpoint URL
  • Payload body
  • HTTP status code returned
  • Timestamp

Review these logs to diagnose delivery issues.

Local development with ngrok

For local testing, use ngrok to create a public tunnel:

ngrok http 3000

The HTTPS URL provided by ngrok can be used as your webhook endpoint URL. Replace it in GitScrum when your tunnel URL changes.

Related