Webhook Troubleshooting

Diagnose failed webhook deliveries using the error messages Debitura returns in the delivery log.

Error Message Reference

Failed deliveries are logged as HTTP {numeric code} (for example, HTTP 401 or HTTP 404). Connection failures use safe messages such as Endpoint connection failed, Endpoint DNS lookup failed, Endpoint TLS connection failed, or Endpoint request timed out; delivery history does not expose raw exception details. The test-delivery endpoint uses the expanded HTTP messages below.

HTTP Errors

Error message	Fix
HTTP 401 (delivery log) / HTTP 401: Unauthorized (test delivery)	Webhook deliveries authenticate via signature verification, not bearer tokens. Remove any auth middleware from your webhook route.
HTTP 404 (delivery log) / HTTP 404: Not Found (test delivery)	Verify the webhook URL. If using Mattermost, Zapier, or Make, confirm you copied the full incoming webhook URL including all path segments.
HTTP 501 (delivery log) / HTTP 501: Not Implemented (test delivery)	If using Mattermost, you may be pointing to an API endpoint (/api/v4/...) instead of an Incoming Webhook URL from Integrations > Incoming Webhooks.

Special case: HTTP 410

An HTTP 410 Gone response automatically disables the webhook subscription. Debitura interprets this as the endpoint being permanently retired. See Retry Behavior for other auto-disable conditions.

Network Errors

Error message	Fix
Cannot reach your endpoint	Verify the URL is publicly accessible over HTTPS. Private IPs (10.x, 172.16-31.x, 192.168.x), localhost, and metadata endpoints are blocked. Only ports 443 and 8443 are allowed.
SSL/TLS certificate error	Install a valid TLS certificate. Self-signed certificates are rejected.
Request timed out after 10 seconds	Return 2xx immediately and process the payload asynchronously.
An unexpected error occurred while testing the webhook. Please try again later or contact support if the problem persists.	Retry, or contact support if the failure persists.

Test Deliveries

Test deliveries use your real webhook secret and identical HMAC-SHA256 signing. If signature verification passes for a test, it will work in production. Test payloads include the header X-Debitura-Test: true and contain synthetic sample data.

When a test delivery fails, the API returns a structured JSON response with a categorized error:

{
  "success": false,
  "httpStatusCode": null,
  "durationMs": 1234,
  "errorMessage": "Cannot reach your endpoint. Verify the URL is correct and publicly accessible.",
  "errorCategory": "NetworkError",
  "testPayload": { "event": "case.created", "data": {} }
}

The errorCategory field is one of TimeoutError, NetworkError, SslError, HttpError, or UnknownError. The errorMessage field always contains a user-friendly explanation.

CRUD Errors

Create, update, and delete operations on webhook subscriptions return structured JSON error responses instead of generic HTML error pages. Validation errors (e.g., invalid URL format, blocked private IP) return 400 Bad Request with specific validation messages in the structured error envelope.

Referral Partner API

The Trigger Test Webhooks endpoint returns 403 Forbidden in production - use testreferral-api.debitura.com for testing. Client API test deliveries work in all environments.