From 730fdcd3e48dd964736eeca54790418632b3a2c0 Mon Sep 17 00:00:00 2001 From: mbasadi Date: Mon, 14 Apr 2025 14:39:37 -0400 Subject: [PATCH 1/2] Add Webhook API documentation for real-time notification events Introduced a new document detailing the Notification Events Webhook API, including its purpose, how it works, supported events, and setup instructions. This addition aims to enhance user understanding and integration capabilities with notification events. --- docs/features/webhook-api.md | 73 ++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/features/webhook-api.md diff --git a/docs/features/webhook-api.md b/docs/features/webhook-api.md new file mode 100644 index 00000000..9a250797 --- /dev/null +++ b/docs/features/webhook-api.md @@ -0,0 +1,73 @@ +# 🪝 Webhook API + +The Notification Events Webhook API allows you to receive real-time updates about notification events such as delivery, opens, and clicks. By setting up a publicly accessible API endpoint, you can track and react to these events programmatically. + +:::note +This feature is currently in beta. +::: + +## Why Use Notification Events Webhook + +Many organizations need to track notification engagement for various purposes: + +- **Build custom analytics dashboards** to measure notification performance +- **Create automated workflows** triggered by specific notification events +- **Track user engagement** with notifications across channels +- **Develop complex integrations** with other systems based on notification events + +## How It Works + +When specific events occur in the notification lifecycle (such as email opens or clicks), our system sends HTTP requests to your designated endpoint with detailed information about the event. + +```js +// Example webhook payload for an email open event +{ + "eventType": "OPEN", + "trackingId": "abc123", + "notificationId": "welcome-email", + "channel": "EMAIL", + "userId": "user-123" +} +``` + +## Dashboard Configuration + +You can easily configure your webhook endpoints and select which events to track through the NotificationAPI dashboard: + +1. Navigate to the Webhook Configuration section in your dashboard +2. Enter your webhook URL (e.g., `https://your-webhook-url.com`) +3. Select the events you want to receive notifications for +4. Click "Save Configuration" + +## Supported Events + +The webhook API currently supports the following notification events: + +| Event | Description | Payload | +| ------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `EMAIL_OPEN` | Triggered when a recipient opens an email notification | `{ eventType: "OPEN", trackingId: string, notificationId: string, channel: "EMAIL", userId: string }` | +| `EMAIL_CLICK` | Triggered when a recipient clicks a link in an email notification | `{ eventType: "CLICK", trackingId: string, notificationId: string, channel: "EMAIL", userId: string }` | + +## Setting Up Your Webhook + +To receive notification events: + +1. Create a publicly accessible API endpoint that can receive HTTP POST requests +2. Configure your webhook URL in the NotificationAPI dashboard +3. Select which events you want to receive (EMAIL_OPEN, EMAIL_CLICK) +4. Implement proper validation of incoming webhook requests +5. Process and store the event data as needed for your use case + +## FAQ + +**Q: What is the format of the webhook requests?** +A: Webhook requests are sent as HTTP POST requests with JSON payloads containing event details such as eventType, trackingId, notificationId, channel, and userId. + +**Q: Can I filter which events I receive?** +A: Yes, you can select which events to receive (EMAIL_OPEN, EMAIL_CLICK) in the dashboard configuration. + +**Q: What response should my endpoint return?** +A: Your endpoint should return a 2xx HTTP status code to acknowledge successful receipt of the webhook. + +**Q: Can I delete or update my webhook configuration?** +A: Yes, you can update your webhook URL or selected events at any time from the dashboard. You can also delete your webhook configuration if you no longer need it. From 2f4261c18689f62fea7b56e7f35d177dd2138bb6 Mon Sep 17 00:00:00 2001 From: mbasadi Date: Mon, 14 Apr 2025 16:46:51 -0400 Subject: [PATCH 2/2] Update webhook API documentation to clarify navigation steps in the dashboard Revised the instructions for configuring webhook endpoints by specifying the "Events Webhook" tab within the "Settings" section of the dashboard. This change aims to improve user clarity and ease of access to webhook configuration. --- docs/features/webhook-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/webhook-api.md b/docs/features/webhook-api.md index 9a250797..d7fa455b 100644 --- a/docs/features/webhook-api.md +++ b/docs/features/webhook-api.md @@ -34,7 +34,7 @@ When specific events occur in the notification lifecycle (such as email opens or You can easily configure your webhook endpoints and select which events to track through the NotificationAPI dashboard: -1. Navigate to the Webhook Configuration section in your dashboard +1. Navigate to the "Events Webhook" tab in the "Settings" section of the your dashboard 2. Enter your webhook URL (e.g., `https://your-webhook-url.com`) 3. Select the events you want to receive notifications for 4. Click "Save Configuration"