Webhooks

Pro outbound webhooks notify your systems when something happens in your workspace — for example when a reward conversion is logged or a client CSV import completes. referDot POSTs JSON to your URL and signs the body with a per-endpoint secret.

• Console page: /#your-slug/settings?focus=webhooks
• Who can configure: Owner or Admin (permission webhooks:manage)
• Production URLs must use HTTPS (http://localhost works for local dev)

1. Open your workspace console → Webhooks (sidebar).
2. Paste your endpoint URL, e.g. https://api.example.com/hooks/referdot.
3. Click Add endpoint. Save the secret shown — you need it to verify signatures on your server.
4. Trigger a test event (log a conversion or import a small CSV) and confirm your server receives a POST.
5. Check Recent deliveries on the same page for SENT or error details.

Each delivery is an HTTP POST with JSON body:

{
  "id": "clx…",
  "event": "conversion.created",
  "createdAt": "2026-09-27T16:30:00.000Z",
  "data": { … }
}

Headers: Content-Type: application/json, X-referDot-Event (event name), X-referDot-Signature (HMAC-SHA256 hex of the raw body). Return any 2xx status within about 12 seconds.

Always verify X-referDot-Signature before trusting the payload. Compute HMAC-SHA256 of the raw request body using your endpoint secret, then compare to the header (use a constant-time compare).

Full Node.js and Python examples: see docs/pro-webhooks.md in the repo, or ask your developer to implement the same HMAC check.

New endpoints from the console subscribe to:

• conversion.created — new reward conversion logged. data: conversionId, referralCode, amount.
• conversion.updated — status changed (e.g. APPROVED, PAID). data: conversionId, status.
• clients.imported — CSV import finished. data: created, skipped.

Endpoints created via API can pass a custom events array. An empty list means “all events.”

• Each attempt appears under Recent deliveries with status SENT or FAILED.
• Failures show lastError (e.g. HTTP 500 or timeout).
• There is no automatic retry yet — fix your endpoint and trigger a new event to test again.
• Use delivery id to dedupe if you receive duplicates from replays.

Create a Catch Hook in Zapier or Make, paste that URL into referDot Webhooks, then map data.* fields to your CRM or spreadsheet. For production, add a signature-verification step on a small server or use a platform that exposes raw body + headers.

Copy this into Cursor or another coding agent. Replace the two placeholders, then have it add a webhook receiver in your server or external app. The signing secret appears only once under Settings → Webhooks when you add the endpoint.

Add a referDot Pro webhook receiver to this codebase so our server (or this external app) can accept signed events from referDot.

Requirements:
- Expose an HTTPS POST route (example path: /hooks/referdot). Local dev may use http://localhost.
- Read the raw request body bytes. Do not parse JSON before verifying the signature.
- Verify header X-referDot-Signature: HMAC-SHA256 hex of the raw body, key = env REFERDOT_WEBHOOK_SECRET. Use a constant-time compare. Reject with 401 if it does not match.
- Header X-referDot-Event matches the JSON field "event".
- JSON body shape: { "id", "event", "createdAt", "data" }.
- Return HTTP 200 within 12 seconds. Do heavier work after the response. referDot does not retry failed deliveries.
- Deduplicate on "id" so a replayed delivery is safe.
- Handle these events:
  - conversion.created — data: conversionId, referralCode, amount, referrerPayout, refereePayout, refereeClientId (some fields may be null)
  - conversion.updated — data: conversionId, status (PENDING | APPROVED | REJECTED | PAID)
  - clients.imported — data: created, skipped
- Store the secret only in environment or a secret manager, never in source control.
- Add a short README note: in referDot open Settings → Webhooks, add this endpoint URL, copy the signing secret once, and set REFERDOT_WEBHOOK_SECRET.

Workspace: REPLACE_WITH_WORKSPACE_NAME
Endpoint URL this app will expose: REPLACE_WITH_PUBLIC_HTTPS_URL
Language/framework: match this repository.

• No deliveries — confirm an endpoint exists, the event type matches, and you triggered an action (conversion log or import).
• FAILED · HTTP 401 — signature verification failing on your side, or middleware rejecting unsigned requests.
• FAILED · timeout — respond 200 immediately and process the payload in a background job.
• Can't access Webhooks — Staff role cannot manage webhooks; ask an Owner or Admin.
• HTTPS required — use a public HTTPS URL in production; tunnel localhost with ngrok if needed.