Troubleshooting

Common issues

"Must be a secure HTTPS URL"

Cause: The URL does not meet webhook URL requirements.

Fix:

• Use https:// (not http://).
• Use a domain name, not localhost or an IP address.
• Ensure the URL is valid and well-formed.

"Secret must be between 32 and 100 characters long"

Cause: The HMAC secret is too short or too long.

Fix: Set the secret to 32 to 100 characters. Use Regenerate for a random secret.

"Please fill in at least one email address"

Cause: Failure notification has no valid emails.

Fix: Add no more than two valid email addresses. Remove empty fields.

Delivery status: Failed

Cause: Your endpoint did not return 2xx, or the request timed out, and retries were exhausted.

Fix:

1. Open the delivery detail sheet and check Last HTTP Code and Last Latency.
2. Inspect the Request Payload to confirm the structure.
3. Check your server logs for errors.
4. Common causes:
   • 401/403: auth failure
   • 404: wrong URL or path
   • 500: server error
   • timeout: endpoint too slow
5. After fixing, use Replay to resend the delivery.

Delivery status: Scheduled

Cause: The last attempt failed; a retry is planned.

Fix: Same as Failed. Fix your endpoint before the next retry.

Signature verification fails

Cause: Verification logic does not match how Monime signs the request.

Fix:

1. Use the raw request body bytes, not parsed JSON.
2. Confirm the correct secret or public key.
3. Check the signature header name and encoding.
4. Use constant-time comparison for HMAC.
5. Inspect a test delivery in the UI.

No deliveries appearing

Cause: Events are not being triggered, or the webhook is misconfigured.

Fix:

1. Confirm the webhook is Active.
2. Confirm you selected the correct events.
3. Trigger a matching event and wait a few seconds.
4. Check filters in the Event Deliveries table.

Replay button disabled

Cause: The webhook is disabled or the replay cooldown is active.

Fix:

1. Enable the webhook if it is disabled.
2. Wait for the cooldown (about 30 seconds) after a successful replay.

Alert emails not received

Cause: Emails may be delayed, filtered, or misconfigured.

Fix:

1. Check spam or junk folders.
2. Confirm the email addresses are correct.
3. Confirm the webhook had actual failures.
4. Alerts are sent after repeated failures, not single errors.

Custom header not received

Cause: Header was invalid or empty when creating the webhook.

Fix:

1. Header names must match [A-Za-z0-9-]+.
2. Header values must be non-empty and printable ASCII.
3. Re-create the webhook or update via API with valid headers.

"No alert emails configured" warning

Cause: The webhook is active but has no failure notification emails.

Fix: Open the webhook details, click Add or Edit under Alert Emails, and add up to two emails.

Developer mode not enabled

Cause: The Space does not have Developer mode turned on.

Fix: Enable Developer mode from the Developer section.

Create button stays disabled

Cause: One or more required fields are invalid or empty.

Fix: Check each field:

• Name is non-empty.
• URL is valid HTTPS, no localhost or IP.
• API release is selected.
• Events include at least one item.
• Alert emails include no more than two valid addresses.
• HMAC secret (if used) is 32 to 100 characters.

400 Bad Request when creating

Cause: Request body is invalid or missing required fields.

Fix: Ensure all required fields are present and valid. If using the API directly, verify the Idempotency-Key header is set.

401 Unauthorized on delivery

Cause: Your endpoint rejected the request, often due to failed signature verification or custom header auth.

Fix:

1. Verify you use the raw body for signature verification.
2. Confirm the secret or public key matches the webhook.
3. If using custom headers for auth, ensure the header value is correct.
4. Check server logs for the exact error.

502, 503, or 504 on delivery

Cause: Your endpoint returned a gateway or server error, or timed out.

Fix:

1. Check your server health and logs.
2. Ensure the endpoint can handle the request within the timeout.
3. Return 2xx quickly and process async.
4. Scale or optimize if the endpoint is overloaded.

Duplicate events processed

Cause: Retries or replays sent the same event again. Your handler did not treat it as a duplicate.

Fix: Implement idempotency. Store processed event IDs and skip duplicates.

Webhook created but no events in list

Cause: The API release has no events or the list failed to load.

Fix: Refresh the page. If the release has no events, choose another release. Contact support if the release should have events.

Quick diagnostic

Self-service first

Before contacting support:

1. Search this doc and the FAQ.
2. Check Testing locally if verification fails.
3. Review Verification and security.
4. Use the Event Deliveries table to inspect failures.
5. Replay after fixing your endpoint to confirm success.

When to contact support

Contact support when:

• You have followed the docs and the issue persists.
• You see an error not covered here.
• You need details on retry policy or timeouts.
• You suspect a bug in the webhook service.