# 2. Webhooks & Event Notifications

User Type: **Training Institute**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## 2. Webhooks & Event Notifications

### 2.1 Webhook Configuration
**What it does:** Lets the Training Institute configure webhooks: the Institute registers an endpoint URL, selects the event types to receive, and the platform sends signed HTTP POSTs to the endpoint when those events occur. The Institute sees the configured webhooks and their status. This pushes real-time events to the Institute's systems.

**Sub-features:**
- Webhook configuration
- Register an endpoint URL
- Select event types to receive
- Signed HTTP POSTs sent on events
- Configured webhooks list
- Webhook status shown
- Configuration available on web and mobile
- Configuration event logging (created, updated)
- Audit logging of the webhook configuration

**Training Institute User Journey:**
1. Training Institute opens the webhook configuration.
2. Training Institute registers an endpoint URL.
3. Training Institute selects the event types to receive.
4. The signed HTTP POSTs are sent on events.
5. The configured webhooks list is shown.
6. The webhook status is shown.
7. Training Institute opens Profile → "Activity" and confirms the configuration events are recorded.

**Rules & Edge Cases:**
- The webhook payload is signed for verification.
- An unreachable endpoint is marked as failing.
- Configuration events (created, updated) are logged with the account and the timestamp.
- The webhook configuration is audit-logged with the account and the timestamp.

### 2.2 Webhook Delivery & Retries
**What it does:** Shows the Training Institute the webhook delivery status: the recent deliveries, the success or failure of each, and the automatic retries for failed deliveries. The Institute can resend a failed delivery manually. This ensures reliable event delivery.

**Sub-features:**
- Webhook delivery log
- Success or failure per delivery
- Automatic retries for failures
- Retry schedule shown
- Manual resend of a failed delivery
- Delivery payload viewable
- Delivery available on web and mobile
- Delivery event logging (delivered, retried)
- Audit logging of the webhook delivery and retries

**Training Institute User Journey:**
1. Training Institute opens the webhook delivery.
2. The webhook delivery log is shown.
3. The success or failure per delivery is shown.
4. The automatic retries for failures are shown.
5. The retry schedule is shown.
6. Training Institute resends a failed delivery manually.
7. Training Institute opens Profile → "Activity" and confirms the delivery events are recorded.

**Rules & Edge Cases:**
- The retries follow an exponential backoff.
- A delivery that exhausts retries is marked as dead.
- Delivery events (delivered, retried) are logged with the account and the timestamp.
- The webhook delivery and retries is audit-logged with the account and the timestamp.

### 2.3 Webhook Security
**What it does:** Manages the security of the Training Institute's webhooks: the signing secret for verifying payloads, the IP allowlist for the platform's sender, and the option to rotate the secret. The Institute sees the security settings and can rotate the secret. This protects the webhook channel from tampering.

**Sub-features:**
- Webhook security settings
- Signing secret for verification
- IP allowlist for the sender
- Rotate the signing secret
- Secret shown only once
- Security available on web and mobile
- Security event logging (secret rotated)
- Audit logging of the webhook security

**Training Institute User Journey:**
1. Training Institute opens the webhook security.
2. The webhook security settings are shown.
3. The signing secret for verification is shown.
4. The IP allowlist for the sender is shown.
5. Training Institute rotates the signing secret.
6. The secret is shown only once.
7. Training Institute opens Profile → "Activity" and confirms the security events are recorded.

**Rules & Edge Cases:**
- The secret is shown only once at creation or rotation.
- A rotation invalidates the previous secret.
- Security events (secret rotated) are logged with the account and the timestamp.
- The webhook security is audit-logged with the account and the timestamp.