Webhook Troubleshooting

Signature Verification Fails (HTTP 401)

1. Did you parse JSON before verifying?

   Always compute HMAC on the raw request body string. Express requires express.raw({ type: 'application/json' }) or accessing req.rawBody.

1. Did you use the wrong secret?

   Each destination has its own unique secret starting with whsec_. Ensure your environment variable matches the exact secret shown in the dashboard.

1. Is system clock skewed?

   Check that your receiver server's clock is synchronized with NTP. Drift beyond 300 seconds is rejected.

Request Timeouts (>15s)

If your receiver performs heavy synchronous work (like sending emails or syncing databases), it may exceed the 15-second timeout:

• Return an HTTP 200 OK immediately after validating the signature.

• Enqueue background jobs to an asynchronous queue (e.g. BullMQ, Celery, or background worker).

Destination URL Rejected (Private IP / SSRF)

Asiyst blocks non-HTTPS destinations and private IP networks. If you are developing locally:

• Use a secure HTTPS tunneling tool like Cloudflare Tunnels, ngrok, or Localtunnel to expose an HTTPS URL to Asiyst.

• Enter the public HTTPS URL in the dashboard.

Events Not Being Received

• Verify the destination is Active (not disabled).

• Check the Subscribed Events list on your destination to ensure the specific event type is checked.

• Open Delivery Logs to check if delivery attempts were made and see their HTTP status codes.