From 98659b69782b23eb2c48553baada2547b9a1562a Mon Sep 17 00:00:00 2001 From: mbasadi Date: Tue, 15 Apr 2025 16:01:55 -0400 Subject: [PATCH 1/3] change the file name --- .../{webhook-api.md => events-webhook.md} | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) rename docs/features/{webhook-api.md => events-webhook.md} (83%) diff --git a/docs/features/webhook-api.md b/docs/features/events-webhook.md similarity index 83% rename from docs/features/webhook-api.md rename to docs/features/events-webhook.md index d7fa455..45d144e 100644 --- a/docs/features/webhook-api.md +++ b/docs/features/events-webhook.md @@ -1,6 +1,6 @@ -# 🪝 Webhook API +# 🪝 Events Webhook -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. +The Notification Events Webhook 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. @@ -39,9 +39,11 @@ You can easily configure your webhook endpoints and select which events to track 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: +The webhook currently supports the following notification events: | Event | Description | Payload | | ------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | @@ -58,6 +60,17 @@ To receive notification events: 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?** From eef46fa5f7c25ac24cfd56b1b6c6da7a55183465 Mon Sep 17 00:00:00 2001 From: mbasadi Date: Tue, 15 Apr 2025 16:08:05 -0400 Subject: [PATCH 2/3] Enhance webhook documentation to include 'FAILED' event support Updated the events section to add the 'FAILED' notification event, including its description and payload details. Adjusted the setup instructions and FAQs to reflect the new event option for improved clarity and user guidance. --- docs/features/events-webhook.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/features/events-webhook.md b/docs/features/events-webhook.md index 45d144e..be18223 100644 --- a/docs/features/events-webhook.md +++ b/docs/features/events-webhook.md @@ -45,10 +45,11 @@ You can easily configure your webhook endpoints and select which events to track The webhook 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 }` | +| 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 }` | +| `FAILED` | Triggered when a notification fails to deliver (for any channel type) | `{ eventType: "FAILED", trackingId: string, notificationId: string, channel: Channels, userId: string }` | ## Setting Up Your Webhook @@ -56,7 +57,7 @@ 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) +3. Select which events you want to receive (EMAIL_OPEN, EMAIL_CLICK, FAILED) 4. Implement proper validation of incoming webhook requests 5. Process and store the event data as needed for your use case @@ -77,10 +78,13 @@ To ensure that webhook requests are legitimate: 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. +A: Yes, you can select which events to receive (EMAIL_OPEN, EMAIL_CLICK, FAILED) 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: When would I receive a FAILED event?** +A: You'll receive a FAILED event whenever a notification on any channel (email, SMS, push, etc.) fails to deliver to the recipient. This could happen for various reasons like invalid recipient details, network issues, service provider failures, or user-specific delivery problems. This event helps you track delivery failures across all your notification channels. + **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 69d42028bf1e894152651789e837aced16745acb Mon Sep 17 00:00:00 2001 From: mbasadi Date: Tue, 15 Apr 2025 16:14:56 -0400 Subject: [PATCH 3/3] Remove outdated security considerations from webhook documentation for clarity and focus on essential implementation steps. --- docs/features/events-webhook.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/features/events-webhook.md b/docs/features/events-webhook.md index be18223..426b3db 100644 --- a/docs/features/events-webhook.md +++ b/docs/features/events-webhook.md @@ -61,17 +61,6 @@ To receive notification events: 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?**