Source: https://docs.debitura.com/developer-concepts/webhooks/troubleshooting

# Webhook Troubleshooting

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

<a id="error-message-reference"></a>

## 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.

<a id="http-errors"></a>

### HTTP Errors

| Error message | Fix |
| --- | --- |
| `HTTP 401` (delivery log) / `HTTP 401: Unauthorized` (test delivery) | Webhook deliveries authenticate via [signature verification](https://docs.debitura.com/developer-concepts/webhooks.md#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](https://docs.debitura.com/developer-concepts/webhooks.md#retry-behavior) for other auto-disable conditions.

<a id="network-errors"></a>

### 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. |

<a id="test-deliveries"></a>

## 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:

```json
{
  "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.

<a id="crud-errors"></a>

## 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](https://docs.debitura.com/referral-partners/integration-guides/webhook-testing.md) endpoint returns `403 Forbidden` in production - use `testreferral-api.debitura.com` for testing. Client API test deliveries work in all environments.