Webhook Configuration

To receive these events, configure a webhook in your Affiliate Admin dashboard with:

URL: Your HTTPS endpoint
Authentication: Optional HMAC SHA-256 signature verification
Interests: Select the specific communication events you want to receive

Webhook Headers

Content-Type: application/json
User-Agent: TelegraMD Webhooks
TelegraMD-Signature: sha256=<hmac_signature>  # When authentication enabled

Payload Fields

Common Fields

id: Unique event identifier
ownerEntity: The patient ID associated with the event
ownerEntityModel: Always "Patient" for communication events
targetEntity: Related entity (Order or Affiliate)
targetEntityModel: Type of target entity
eventTitle: Human-readable event title
eventDescription: Detailed description of the event
eventType: Machine-readable event identifier
createdAt: Timestamp when event was created
updatedAt: Timestamp when event was last updated

eventData Object

performedBy: Information about who initiated the communication
- id: User ID who performed the action
- role: User role (affiliate_admin, provider, etc.)
- name: Full name of the user

Message Event Additional Fields

patientConversationId: ID of the conversation channel
message: Content of the message sent
type: Message type (usually "MESG")
channelType: Type of communication channel (clinical, support, etc.)
sender: ID of the message sender
senderRole: Role of the message sender

Security

When webhook authentication is enabled:

A shared secret is configured in your webhook settings
Each webhook payload is signed using HMAC SHA-256
The signature is included in the TelegraMD-Signature header
Verify the signature to ensure webhook authenticity

Testing

Use tools like ngrok to create a local tunnel for testing webhook delivery during development.

Error Handling

Webhook endpoints should return 2xx status codes for successful processing
Non-2xx responses may trigger retry attempts
Ensure your endpoint can handle duplicate deliveries idempotently