diff --git a/docs/features/webhook-api.md b/docs/features/events-webhook.md similarity index 62% rename from docs/features/webhook-api.md rename to docs/features/events-webhook.md index d7fa455..426b3db 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,14 +39,17 @@ 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 | -| ------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| `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 @@ -54,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 @@ -64,10 +67,13 @@ To receive notification events: 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.