Webhook Issues

Webhooks Not Delivering

Check endpoint URL

• Must be HTTPS (HTTP is rejected)
• Must return a 2xx status code within 10 seconds
• Must be publicly accessible (not localhost or private IPs)

Check delivery logs

Go to Settings > Webhooks, click on your webhook, and review the delivery log. Each attempt shows:

• HTTP status code returned by your endpoint
• Response time
• Error message (if any)

Check event selection

Verify you have subscribed to the correct events. Go to Settings > Webhooks and confirm the event types are checked.

Signature Verification Failing

Common causes:

1. Using parsed JSON instead of raw body — HMAC must be computed on the raw request body string, not JSON.stringify(parsedObject)
2. Wrong secret — Copy the secret again from Settings > Webhooks
3. Encoding mismatch — Ensure you compare hex strings, not binary buffers

Duplicate Deliveries

VULK retries failed deliveries up to 3 times with exponential backoff. If your endpoint returns a 2xx but processes slowly, you may see duplicates. Make your handler idempotent using the event ID.

Test Delivery Not Arriving

• Check your server logs — the test payload may have arrived but been rejected
• Verify firewall rules allow inbound HTTPS from external IPs
• Try a service like webhook.site to verify VULK is sending correctly