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 ("2026-08-17"), timestamp, timestamp_epoch, affiliate_id, the patient-identity block (patient_id, patient_external_id, patient_marketing_consent, is_returning_patient), plus per-category allowlisted fields. Clinical PHI and message content are stripped; patient-identity fields such as patient_id and patient_external_id are retained when a linked patient exists. Forwarding a v2 payload still requires appropriate privacy controls. Deduplicate on event_id — not on timestamp / timestamp_epoch.

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 clinical PHI and message content; patient-identity fields such as patient_id and patient_external_id are retained when a linked patient exists. Forwarding a v2 payload still requires appropriate privacy controls. 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.