Docs/Using Plugins/Webhook Notifications

Webhook Notifications

The Reminder plugin can send an HTTP POST to a URL of your choice after each reminder delivery attempt. Use webhooks to keep an external system — such as a CRM, a helpdesk, or a custom dashboard — in sync with reminder status changes in real time.

Configuring the Webhook URL

Set the webhook URL when creating or updating the plugin configuration:

POST /api/reminder/configuration
PUT  /api/reminder/configuration

Include the integrationSettings field in the request body:

{
  "integrationSettings": {
    "webhookUrl": "https://your-system.com/api/reminder-webhook"
  }
}

The webhook URL is stored with the configuration and used for all reminder items under that configuration. To disable webhooks, set the URL to an empty string or omit the field.

Webhook Payload

When a delivery attempt completes — successfully or not — the plugin sends an HTTP POST to the configured URL with this JSON body:

Field	Type	Description
`id`	string	The unique identifier of the reminder item.
`date`	datetime	The UTC timestamp of the delivery attempt.
`status`	string	The reminder's current status: `active`, `completed`, `expired`, or `cancelled`.
`detail`	string	A human-readable description of the action, e.g. `Reminder sent` or `Send failed`.

Example payload:

{
  "id": "rem-abc123",
  "date": "2025-06-01T02:00:00Z",
  "status": "completed",
  "detail": "Reminder sent"
}

When Webhooks Are Called

A webhook is dispatched after each delivery attempt. The trigger events are:

Event	`status` value	`detail` value
Reminder delivered successfully	`active` or `completed`	`Reminder sent`
Delivery attempt failed	`active`	`Send failed`
Reminder advanced to next send time after max retries	`active`	Varies
All send times exhausted after last delivery	`completed`	`Reminder sent`

If no send times remain after a successful delivery, the status in the payload will be completed.

Delivery Behavior

Webhooks are sent as fire-and-forget HTTP POST requests.
If your endpoint returns an error or is unreachable, the failure is logged but does not affect reminder processing or retry logic.
There is no automatic retry for failed webhook deliveries.
Your endpoint must respond within a reasonable timeout to avoid connection errors on the plugin side.

Securing Your Webhook Endpoint

The plugin does not sign webhook payloads. To protect your endpoint from unauthorized calls:

Use a non-guessable path, e.g. include a random token in the URL: https://your-system.com/hooks/reminder/a3f9b2c1d4.
Verify the id field against your own records before processing the event.
Restrict your endpoint to the known IP range of the plugin host.

Plugin Setup — where the webhook URL is configured.
Processing and Delivery — when webhooks are triggered during the delivery flow.
Reminder Overview

PreviousProcessing and Delivery