Webhook Troubleshooting

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

Error Message Reference

When a delivery fails, Debitura logs a specific error message. Standard HTTP errors are logged as HTTP {code}: {reason} - check your server logs for details. The table below covers errors with Debitura-specific causes or fixes.

HTTP Errors

Error message	Fix
HTTP 401: Unauthorized	Webhook deliveries authenticate via signature verification, not bearer tokens. Remove any auth middleware from your webhook route.
HTTP 404: Not Found	Verify the webhook URL. If using Mattermost, Zapier, or Make, confirm you copied the full incoming webhook URL including all path segments.
HTTP 501: Not Implemented	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.
Network error: {details}	The {details} suffix contains the underlying socket or HTTP error.
Unexpected error: {details}	Contact support with the error details if the cause is unclear.

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:

{
  "category": "ConnectionRefused",
  "message": "Cannot reach your endpoint. Verify the URL is publicly accessible over HTTPS.",
  "statusCode": null,
  "responseBody": null
}

Error categories include ConnectionRefused, Timeout, SslError, DnsResolutionFailed, NonSuccessStatusCode, and Unknown. The message 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 field-level messages.

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.