Skip to content
NovaVMS Manual

Webhook delivery failed

Webhook delivery failed

Symptom

In the admin UI’s webhook delivery log, a delivery shows Failed with the error webhook_delivery_failed. NovaVMS retries failed deliveries with exponential backoff (1m, 5m, 15m, 1h, 6h) and then gives up.

Likely causes

  1. Your endpoint returned a non-2xx response.
  2. Your endpoint took longer than 10 seconds to respond. NovaVMS closes the connection at the timeout.
  3. The TLS handshake failed — expired cert, unknown CA, or SNI mismatch.
  4. Your receiver’s signature-verification logic rejected the payload, so you returned a 4xx on purpose.

Fix

If your endpoint returned non-2xx

  1. Open the delivery log entry in the admin UI. The Response body field shows the first 1 KB your endpoint returned.
  2. Reproduce locally against the X-NovaVMS-Signature header and body shown in the log.
  3. Fix the handler. Return 200 OK within 10 seconds. Do the heavy work asynchronously in your own queue.

If the request timed out

NovaVMS waits 10 seconds for a response. If your handler is synchronous and slow:

  1. Return 202 Accepted immediately.
  2. Enqueue the work to your own job queue.
  3. Process the payload out-of-band.

If TLS failed

  1. Confirm the cert chain is valid: curl -vI https://your-endpoint/path from a clean network. NovaVMS uses the system CA bundle — self-signed certs are rejected.
  2. Check the cert has not expired.
  3. Confirm SNI is correctly configured if you host multiple domains on one IP.

If signature verification failed on your side

  1. Confirm you are using the shared secret from the webhook’s Signing tab in the admin UI, not the org’s API token.
  2. Confirm you are computing HMAC-SHA256 over the raw request body, not a re-serialised JSON version. See webhook signing.
  3. Rotate the secret if you suspect it was leaked.

Verify

  1. In the admin UI, open the failed delivery and click Replay.
  2. The replay shows Succeeded with a 200 response.
  3. The next live event also delivers successfully — check the top of the log.

If none of this worked

  • Collect the request_id from the delivery log entry and include it in a support ticket.
  • See also: API error code reference.