Webhook Failures

Symptom A: Webhook endpoint returns 4xx/5xx

How to check: Dashboard → Property → Webhooks → Delivery Log — shows status codes and response bodies.

Causes and fixes:

Status code	Likely cause	Fix
401	Signature verification failing	Check your verification code — see Webhook Security
400	Your endpoint rejects the payload format	Log the raw body and check against the payload schema
404	Endpoint URL has changed	Update the webhook URL in Property → Webhooks → [Webhook] → Edit
500	Bug in your webhook handler	Check your server logs for the error
timeout	Your endpoint takes too long to respond	Respond with 200 immediately, process async

---

Symptom B: Webhook signature verification failing

Cause: Most common reasons:

1. Signing string built incorrectly — must be {timestamp}.{raw_body} (not parsed JSON)
2. Using a different secret than the one shown in the Dashboard
3. Reading a buffered/modified body instead of the raw bytes

Fix: Ensure you read the raw request body before any JSON parsing. In Express:

// MUST use raw body middleware
app.use('/webhooks', express.raw({ type: '*/*' }));

---

Symptom C: Webhook deliveries are delayed

Cause: ConsentForge retries failed deliveries with exponential backoff — delays are expected after initial failures.

Fix: Fix the underlying error (see Symptom A). Once your endpoint returns 2xx, future deliveries will be immediate.

---

Symptom D: Missing deliveries — events not received

How to check: Compare the Dashboard's delivery log count with your server's received count.

Cause: Some events may have exhausted all retry attempts (5 attempts over ~2 hours).

Fix: Property → Webhooks → Delivery Log → Filter: Failed — use the Replay button to re-send failed deliveries.