Webhooks & Event Subscriptions

Webhooks deliver Medipal events to an external HTTPS endpoint the moment they happen, so other systems can react without polling. Workflows react to the same events inside Medipal; webhooks push them out. Both are configured in the Admin Panel and both are fed by the same event stream.

Events

The event families are the same as for workflows: questionnaires, submissions, users, folders and sign-in events. See the list in Workflows. Each delivery is a JSON document with a standard envelope (event type, source, subject, time, unique id) and the event data.

Creating a webhook

1. Open Admin Panel → Configuration → Webhooks and choose Create Webhook.
2. Enter a name, the endpoint URL (HTTPS) and an optional description.
3. Select the event types to receive, or All events.
4. Leave Enabled on and save.
5. Copy the secret shown once after creation and store it with your receiving system. It is used to sign every delivery so the receiver can verify that a call really came from your instance.

The technical details of the request, headers and signature verification are in Events & Webhooks.

Managing webhooks

Action	Effect
Edit	Change the name, URL, description or event types.
Enable / Disable	A disabled webhook keeps its configuration but receives nothing.
Rotate Secret	Issues a new secret and shows it once. Deliveries signed with the old secret stop immediately, so update the receiver first, then rotate.
View Deliveries	Opens the delivery log for this webhook.
Delete	Removes the webhook and its delivery history.

Delivery log and retries

View Deliveries shows every event sent to the endpoint with its status, the HTTP status returned, the number of attempts and the delivery time. Each entry can be expanded to see the payload that was sent, the response body and any error.

Status	Meaning
Pending	Not attempted yet, or waiting for the next retry.
Delivered	The endpoint answered with a success status.
Failed	The last attempt failed; further attempts are scheduled.
Exhausted	All attempts failed; no more automatic retries.

Failed deliveries are retried automatically with increasing intervals. Retry forces an immediate new attempt for one delivery. Old delivery records are cleaned up automatically after a retention period.

Filtering events

A webhook is filtered by event type only. If the receiver should only see events for one questionnaire or folder, either filter on the receiving side using the event's subject and data, or use a workflow with an HTTP node, which supports full conditions.

Permissions

Webhooks are administrative: viewing requires webhook read rights, managing requires webhook write rights. These are not part of the standard clinician role. See Users, Roles & Scopes.

Troubleshooting

Symptom	Likely cause	What to do
Deliveries stay Pending	The endpoint is unreachable or slow	Check the endpoint URL and that it accepts HTTPS POST; watch the response body in the log.
Endpoint rejects every call with 401 or 403	Receiver expects a different authentication than the signature	Configure the receiver to verify the signature header instead of a static token.
Receiver reports invalid signature	The secret was rotated, or the receiver signs a modified body	Update the secret on the receiver; verify against the raw request body.
Duplicate events at the receiver	A retry after a slow success response	Make the receiver idempotent using the delivery id header.
No events arrive at all	Webhook disabled, or event types not selected	Enable it and check the event type list.