Webhook Configuration

Configure a webhook in your Affiliate Admin dashboard with:

• URL — your HTTPS endpoint
• Authentication — optional HMAC-SHA256 signature verification
• Interests — the specific events you want to receive
• Payload version — v1 (legacy, full raw events) or v2 (sanitized envelopes, PHI stripped). Newly created webhooks default to v2; existing webhooks stay on v1 until upgraded. See Webhooks v2 — Overview.

Request headers

Every delivery includes:

Content-Type: application/json
User-Agent: TelegraMD Webhooks
TelegraMD-Signature: <signature>   # when authentication is enabled

The TelegraMD-Signature value differs by payload version:

• v2 — t={unix_seconds},sha256={base64_hmac} (timestamped, replay-protected)
• v1 — sha256={base64_hmac} (no timestamp)

See Signature Verification for how to verify each, and always use a constant-time comparison.

Payload shape

The payload shape depends on the version:

• v1 — the full raw event document: eventType, _id/id, ownerEntity, targetEntity, eventTitle, eventDescription, createdAt, updatedAt, and a nested eventData object (which includes PHI).
• v2 — a flat, sanitized envelope: event_type, event_id, api_version, timestamp, affiliate_id, the patient-identity block (patient_id, patient_external_id, patient_marketing_consent, is_returning_patient), plus per-category allowlisted fields. PHI is stripped.

Which specific fields each event carries — and which are guaranteed vs. conditional — is documented per event, and summarized on the Field Guarantees page.

🚧

eventTitle / eventDescription are free text (v1 only) and can change without notice. Never parse them for business logic — key off eventType and the structured fields.

🔒

PHI: v1 payloads contain PHI (the full patient document, message bodies, tracking details, etc.). v2 strips it. If you don't need PHI, prefer v2. Message content specifically (eventData.message on communication events) is removed in v2.

Delivery, retries, and idempotency

Respond 2xx within 5 seconds; failures and timeouts are retried (6 total attempts with exponential backoff), delivery is at-least-once, and event ids are stable across retries. Full details on the Delivery & Retries page.

Testing

Use a tunnel such as ngrok, or https://webhook.site, to inspect deliveries during development. Note the affiliate-admin "test" button does not always reproduce a faithful v1 payload for every event — validate against a real event where possible.